feat: auth & admin

app/infrastructure/db/models/__init__.py

@@ -0,0 +1,10 @@
+"""ORM models package.
+
+Importing this package registers every model on ``Base.metadata`` so Alembic
+autogenerate and ``create_all`` (tests) see the full schema. ``alembic/env.py``
+imports it for exactly this side effect.
+"""
+
+from app.infrastructure.db.models.user import RefreshTokenModel, UserModel
+
+__all__ = ["RefreshTokenModel", "UserModel"]

app/infrastructure/db/models/mixins.py

@@ -0,0 +1,36 @@
+"""Reusable mapped-column mixins for ORM models."""
+
+import datetime as dt
+import uuid
+
+from sqlalchemy import DateTime, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class UUIDPrimaryKeyMixin:
+    """``id`` UUID primary key, generated application-side.
+
+    Generating in Python (not a DB default) keeps ids available before flush —
+    important because ``track.id`` is the client-facing ``content_id``.
+    """
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+
+
+class TimestampMixin:
+    """``created_at`` / ``updated_at``, server-managed.
+
+    Present on every user-mutable entity for future delta-sync (plan §4).
+    """
+
+    created_at: Mapped[dt.datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+    updated_at: Mapped[dt.datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )

app/infrastructure/db/models/user.py

@@ -0,0 +1,45 @@
+"""ORM models for users and refresh tokens."""
+
+import datetime as dt
+import uuid
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.infrastructure.db.base import Base
+from app.infrastructure.db.models.mixins import TimestampMixin, UUIDPrimaryKeyMixin
+
+
+class UserModel(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "users"
+
+    username: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
+    # Admin is a single flag in Phase 1 — no role system (plan §3.5).
+    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+
+class RefreshTokenModel(UUIDPrimaryKeyMixin, Base):
+    """A persisted, revocable refresh token (offline-first sessions).
+
+    Stores only a *hash* of the token, never the raw JWT. Rotated on every
+    refresh (old jti revoked, new row added); logout revokes the current jti.
+    """
+
+    __tablename__ = "refresh_tokens"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"),
+        index=True,
+        nullable=False,
+    )
+    jti: Mapped[uuid.UUID] = mapped_column(unique=True, index=True, nullable=False)
+    token_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    expires_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    revoked_at: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[dt.datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: dt.datetime.now(dt.UTC),
+        nullable=False,
+    )