fastapi-forge-cli 0.1.0__py3-none-any.whl

fastapi_forge/templates/with_rbac/alembic/versions/2255ba4f9604_fresh_baseline.py

@@ -0,0 +1,204 @@
+"""Initial authentication, RBAC, and audit schema.
+
+Revision ID: 2255ba4f9604
+Revises:
+Create Date: 2026-08-13 15:57:46.646562
+"""
+
+from typing import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "2255ba4f9604"
+down_revision: str | Sequence[str] | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _base_columns() -> list[sa.Column]:
+    return [
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("is_deleted", sa.Boolean(), server_default=sa.false(), nullable=False),
+        sa.Column("deleted_at", sa.DateTime(timezone=True)),
+        sa.Column("deletion_note", sa.Text()),
+    ]
+
+
+def upgrade() -> None:
+    for schema in ("auth", "rbac", "app"):
+        op.execute(f"CREATE SCHEMA IF NOT EXISTS {schema}")
+
+    op.create_table(
+        "users",
+        *_base_columns(),
+        sa.Column("email", sa.String(255), nullable=False),
+        sa.Column("username", sa.String(100), nullable=False),
+        sa.Column("full_name", sa.String(255), nullable=False),
+        sa.Column("hashed_password", sa.String(255), nullable=False),
+        sa.Column("is_active", sa.Boolean(), server_default=sa.true(), nullable=False),
+        sa.Column("is_superuser", sa.Boolean(), server_default=sa.false(), nullable=False),
+        sa.Column("is_verified", sa.Boolean(), server_default=sa.false(), nullable=False),
+        sa.Column("last_login_at", sa.DateTime(timezone=True)),
+        sa.UniqueConstraint("email"),
+        sa.UniqueConstraint("username"),
+        schema="auth",
+    )
+    op.create_index("ix_users_email", "users", ["email"], schema="auth")
+    op.create_index("ix_users_username", "users", ["username"], schema="auth")
+
+    op.create_table(
+        "permissions",
+        *_base_columns(),
+        sa.Column("code", sa.String(100), nullable=False),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column("description", sa.Text()),
+        sa.Column("is_active", sa.Boolean(), server_default=sa.true(), nullable=False),
+        sa.UniqueConstraint("code"),
+        schema="rbac",
+    )
+    op.create_index("ix_permissions_code", "permissions", ["code"], schema="rbac")
+
+    op.create_table(
+        "roles",
+        *_base_columns(),
+        sa.Column("name", sa.String(100), nullable=False),
+        sa.Column("description", sa.Text()),
+        sa.Column("is_active", sa.Boolean(), server_default=sa.true(), nullable=False),
+        sa.Column(
+            "parent_role_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("rbac.roles.id", ondelete="SET NULL"),
+        ),
+        sa.UniqueConstraint("name"),
+        schema="rbac",
+    )
+    op.create_index("ix_roles_name", "roles", ["name"], schema="rbac")
+    op.create_index("ix_roles_parent_role_id", "roles", ["parent_role_id"], schema="rbac")
+
+    op.create_table(
+        "user_roles",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("auth.users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("role_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("rbac.roles.id", ondelete="CASCADE"), nullable=False),
+        sa.UniqueConstraint("user_id", "role_id", name="uq_user_roles_user_id_role_id"),
+        schema="rbac",
+    )
+    op.create_table(
+        "role_permissions",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("role_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("rbac.roles.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("permission_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("rbac.permissions.id", ondelete="CASCADE"), nullable=False),
+        sa.UniqueConstraint("role_id", "permission_id", name="uq_role_permissions_role_id_permission_id"),
+        schema="rbac",
+    )
+    op.create_table(
+        "user_permissions",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("auth.users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("permission_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("rbac.permissions.id", ondelete="CASCADE"), nullable=False),
+        sa.UniqueConstraint("user_id", "permission_id", name="uq_user_permissions_user_id_permission_id"),
+        schema="rbac",
+    )
+
+    op.create_table(
+        "email_verification_tokens",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("auth.users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("token", sa.String(255), unique=True, nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("used_at", sa.DateTime(timezone=True)),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        schema="auth",
+    )
+    op.create_table(
+        "password_reset_tokens",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("auth.users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("token", sa.String(255), unique=True, nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("used_at", sa.DateTime(timezone=True)),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        schema="auth",
+    )
+    op.create_table(
+        "user_sessions",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("auth.users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("refresh_jti", sa.String(64), unique=True, nullable=False),
+        sa.Column("previous_refresh_jti", sa.String(64)),
+        sa.Column("user_agent", sa.Text()),
+        sa.Column("ip_address", sa.String(45)),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("revoked_at", sa.DateTime(timezone=True)),
+        sa.Column("last_used_at", sa.DateTime(timezone=True)),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        schema="auth",
+    )
+    op.create_index("ix_user_sessions_user_active", "user_sessions", ["user_id", "revoked_at"], schema="auth")
+
+    op.create_table(
+        "revoked_tokens",
+        *_base_columns(),
+        sa.Column("jti", sa.String(64), unique=True, nullable=False),
+        sa.Column("token_type", sa.String(20), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        schema="auth",
+    )
+
+    op.create_table(
+        "notifications",
+        *_base_columns(),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("auth.users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("title", sa.String(255), nullable=False),
+        sa.Column("body", sa.Text(), nullable=False),
+        sa.Column("notification_type", sa.String(100), nullable=False),
+        sa.Column("channel", sa.String(50), server_default="in_app", nullable=False),
+        sa.Column("is_read", sa.Boolean(), server_default=sa.false(), nullable=False),
+        sa.Column("read_at", sa.DateTime(timezone=True)),
+        sa.Column("payload", postgresql.JSONB()),
+        schema="app",
+    )
+
+    op.create_table(
+        "audit_logs",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("auth.users.id", ondelete="SET NULL")),
+        sa.Column("user_email", sa.String(255)),
+        sa.Column("action", sa.String(100), nullable=False),
+        sa.Column("resource", sa.String(100), nullable=False),
+        sa.Column("resource_id", sa.String(255)),
+        sa.Column("old_values", postgresql.JSONB()),
+        sa.Column("new_values", postgresql.JSONB()),
+        sa.Column("log_metadata", postgresql.JSONB()),
+        sa.Column("ip_address", sa.String(45)),
+        sa.Column("user_agent", sa.Text()),
+        sa.Column("request_id", sa.String(100)),
+        schema="app",
+    )
+    op.create_index("ix_audit_resource_action", "audit_logs", ["resource", "action"], schema="app")
+    op.create_index("ix_audit_user_resource", "audit_logs", ["user_id", "resource"], schema="app")
+
+
+def downgrade() -> None:
+    for table, schema in (
+        ("audit_logs", "app"),
+        ("notifications", "app"),
+        ("revoked_tokens", "auth"),
+        ("user_sessions", "auth"),
+        ("password_reset_tokens", "auth"),
+        ("email_verification_tokens", "auth"),
+        ("user_permissions", "rbac"),
+        ("role_permissions", "rbac"),
+        ("user_roles", "rbac"),
+        ("roles", "rbac"),
+        ("permissions", "rbac"),
+        ("users", "auth"),
+    ):
+        op.drop_table(table, schema=schema)
+    for schema in ("app", "rbac", "auth"):
+        op.execute(f"DROP SCHEMA IF EXISTS {schema}")

fastapi_forge/templates/with_rbac/alembic.ini

@@ -0,0 +1,35 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers = console
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

fastapi_forge/templates/with_rbac/app/__init__.py

@@ -0,0 +1 @@
+

fastapi_forge/templates/with_rbac/app/api/__init__.py

@@ -0,0 +1 @@
+

fastapi_forge/templates/with_rbac/app/api/v1/__init__.py

@@ -0,0 +1 @@
+

fastapi_forge/templates/with_rbac/app/api/v1/api.py

@@ -0,0 +1,34 @@
+from fastapi import APIRouter
+
+from app.api.v1.audit_logs.router import router as audit_logs_router
+from app.api.v1.auth.router import router as auth_router
+from app.api.v1.health.router import router as health_router
+from app.api.v1.permissions.router import router as permissions_router
+from app.api.v1.roles.router import router as roles_router
+from app.api.v1.users.router import router as users_router
+
+api_router = APIRouter(prefix="/api/v1")
+
+API_ROUTES = (
+    (health_router, "/api/v1", ["Health"]),
+    (auth_router, "/api/v1/auth", ["Authentication"]),
+    (users_router, "/api/v1/users", ["Users"]),
+    (permissions_router, "/api/v1/permissions", ["Permissions"]),
+    (roles_router, "/api/v1/roles", ["Roles"]),
+    (audit_logs_router, "/api/v1/audit-logs", ["Audit Logs"]),
+)
+
+
+def register_api_routes(app) -> None:
+    for route, prefix, tags in API_ROUTES:
+        kwargs = {"prefix": prefix}
+        if tags is not None:
+            kwargs["tags"] = tags
+        app.include_router(route, **kwargs)
+
+
+for route, prefix, tags in API_ROUTES:
+    relative_prefix = prefix.removeprefix("/api/v1")
+    api_router.include_router(route, prefix=relative_prefix, tags=tags)
+
+router = api_router

fastapi_forge/templates/with_rbac/app/api/v1/audit_logs/__init__.py

@@ -0,0 +1 @@
+

fastapi_forge/templates/with_rbac/app/api/v1/audit_logs/repository.py

@@ -0,0 +1,38 @@
+from sqlalchemy import func, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models.audit_log import AuditLog
+from app.helper.pagination_helper import apply_pagination
+
+
+class AuditLogRepository:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def list(
+        self,
+        page: int,
+        page_size: int,
+        pagination: bool,
+        search: str | None = None,
+    ) -> tuple[list[AuditLog], int]:
+        query = select(AuditLog)
+        if search:
+            pattern = f"%{search.strip()}%"
+            query = query.where(
+                or_(
+                    AuditLog.action.ilike(pattern),
+                    AuditLog.resource.ilike(pattern),
+                    AuditLog.user_email.ilike(pattern),
+                    AuditLog.resource_id.ilike(pattern),
+                )
+            )
+        total = (
+            await self.session.execute(
+                select(func.count()).select_from(query.subquery())
+            )
+        ).scalar_one()
+        query = query.order_by(AuditLog.created_at.desc())
+        query = apply_pagination(query, page, page_size, pagination)
+        result = await self.session.execute(query)
+        return list(result.scalars().all()), total

fastapi_forge/templates/with_rbac/app/api/v1/audit_logs/router.py

@@ -0,0 +1,50 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.v1.audit_logs.repository import AuditLogRepository
+from app.api.v1.audit_logs.schema import AuditLogResponse
+from app.core.dependencies import get_async_db, require_any_permission
+from app.core.responses import paginated_response, success_response
+from app.helper.pagination_helper import PaginationParams
+
+router = APIRouter()
+
+
+@router.get(
+    "",
+    dependencies=[Depends(require_any_permission("admin:write", "audit_logs:read"))],
+    summary="List audit log entries",
+)
+async def list_audit_logs(
+    pagination: PaginationParams = Depends(),
+    db: AsyncSession = Depends(get_async_db),
+):
+    entries, total = await AuditLogRepository(db).list(
+        page=pagination.page,
+        page_size=pagination.page_size,
+        pagination=pagination.pagination,
+        search=pagination.search,
+    )
+    items = [
+        AuditLogResponse(
+            id=entry.id,
+            created_at=entry.created_at,
+            user_id=entry.user_id,
+            user_email=entry.user_email,
+            action=entry.action,
+            resource=entry.resource,
+            resource_id=entry.resource_id,
+            old_values=entry.old_values,
+            new_values=entry.new_values,
+            metadata=entry.log_metadata,
+            ip_address=entry.ip_address,
+            user_agent=entry.user_agent,
+            request_id=entry.request_id,
+        ).model_dump()
+        for entry in entries
+    ]
+    if not pagination.pagination:
+        return success_response(data=items)
+    return paginated_response(
+        items, total, pagination.page, pagination.page_size
+    )

fastapi_forge/templates/with_rbac/app/api/v1/audit_logs/schema.py

@@ -0,0 +1,21 @@
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from app.utils.casing import CamelModel
+
+
+class AuditLogResponse(CamelModel):
+    id: UUID
+    created_at: datetime
+    user_id: UUID | None = None
+    user_email: str | None = None
+    action: str
+    resource: str
+    resource_id: str | None = None
+    old_values: dict[str, Any] | None = None
+    new_values: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+    ip_address: str | None = None
+    user_agent: str | None = None
+    request_id: str | None = None

fastapi_forge/templates/with_rbac/app/api/v1/auth/repository.py

@@ -0,0 +1,179 @@
+from typing import Optional
+from uuid import UUID
+from datetime import datetime, timezone
+
+from sqlalchemy import select, delete, exists
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.db.models import (
+    EmailVerificationToken,
+    Role,
+    PasswordResetToken,
+    RevokedToken,
+    User,
+    UserSession,
+)
+from app.repositories.base import BaseRepository
+from app.core.security import hash_opaque_token
+
+
+class UserRepository(BaseRepository[User]):
+    def __init__(self, session: AsyncSession):
+        super().__init__(User, session)
+
+    async def get_by_email(self, email: str) -> Optional[User]:
+        q = (
+            select(User)
+            .where(User.email == email.lower(), User.is_deleted == False)
+            .options(
+                selectinload(User.roles).selectinload(Role.permissions),
+                selectinload(User.extra_permissions),
+            )
+        )
+        result = await self.session.execute(q)
+        return result.scalar_one_or_none()
+
+    async def get_by_username(self, username: str) -> Optional[User]:
+        q = select(User).where(
+            User.username == username.lower(), User.is_deleted == False
+        )
+        result = await self.session.execute(q)
+        return result.scalar_one_or_none()
+
+    async def get_with_permissions(self, user_id: UUID | str) -> Optional[User]:
+        """Load user with all permissions eagerly (for JWT construction)."""
+        if isinstance(user_id, str):
+            try:
+                user_id = UUID(user_id)
+            except ValueError:
+                return None
+
+        q = (
+            select(User)
+            .where(User.id == user_id, User.is_deleted == False)
+            .options(
+                selectinload(User.roles).selectinload(Role.permissions),
+                selectinload(User.extra_permissions),
+            )
+        )
+        result = await self.session.execute(q)
+        return result.scalar_one_or_none()
+
+    def collect_permissions(self, user: User) -> list[str]:
+        """Flatten role + individual permissions into a deduplicated list of codes."""
+        codes: set[str] = set()
+        role = self.get_role(user)
+        if role:
+            for perm in role.permissions:
+                if not perm.is_deleted and perm.is_active:
+                    codes.add(perm.code)
+        for perm in user.extra_permissions:
+            if not perm.is_deleted and perm.is_active:
+                codes.add(perm.code)
+        if user.is_superuser or (role and role.name.upper() == "SUPER ADMIN"):
+            codes.add("*")  # wildcard — superuser has everything
+        return sorted(codes)
+
+    def get_role(self, user: User) -> Role | None:
+        for role in user.roles:
+            if not role.is_deleted and role.is_active:
+                return role
+        return None
+
+    def collect_role_name(self, user: User) -> str | None:
+        role = self.get_role(user)
+        return role.name if role else None
+
+class RevokedTokenRepository(BaseRepository[RevokedToken]):
+    def __init__(self, session: AsyncSession):
+        super().__init__(RevokedToken, session)
+
+    async def revoke(self, jti: str, token_type: str, expires_at: datetime) -> None:
+        if await self.is_revoked(jti):
+            return
+
+        self.session.add(
+            RevokedToken(jti=jti, token_type=token_type, expires_at=expires_at)
+        )
+        await self.session.flush()
+
+    async def is_revoked(self, jti: str) -> bool:
+        await self.delete_expired()
+        q = select(exists().where(RevokedToken.jti == jti))
+        result = await self.session.execute(q)
+        return bool(result.scalar())
+
+    async def delete_expired(self) -> None:
+        await self.session.execute(
+            delete(RevokedToken).where(
+                RevokedToken.expires_at <= datetime.now(timezone.utc)
+            )
+        )
+
+
+class EmailVerificationTokenRepository(BaseRepository[EmailVerificationToken]):
+    def __init__(self, session: AsyncSession):
+        super().__init__(EmailVerificationToken, session)
+
+    async def get_valid(self, token: str) -> Optional[EmailVerificationToken]:
+        q = select(EmailVerificationToken).where(
+            EmailVerificationToken.token == hash_opaque_token(token),
+            EmailVerificationToken.used_at.is_(None),
+            EmailVerificationToken.expires_at > datetime.now(timezone.utc),
+        )
+        result = await self.session.execute(q)
+        return result.scalar_one_or_none()
+
+
+class PasswordResetTokenRepository(BaseRepository[PasswordResetToken]):
+    def __init__(self, session: AsyncSession):
+        super().__init__(PasswordResetToken, session)
+
+    async def get_valid(self, token: str) -> Optional[PasswordResetToken]:
+        q = select(PasswordResetToken).where(
+            PasswordResetToken.token == hash_opaque_token(token),
+            PasswordResetToken.used_at.is_(None),
+            PasswordResetToken.expires_at > datetime.now(timezone.utc),
+        )
+        result = await self.session.execute(q)
+        return result.scalar_one_or_none()
+
+
+class UserSessionRepository(BaseRepository[UserSession]):
+    def __init__(self, session: AsyncSession):
+        super().__init__(UserSession, session)
+
+    async def get_active_by_refresh_jti(self, jti: str) -> Optional[UserSession]:
+        q = select(UserSession).where(
+            UserSession.refresh_jti == jti,
+            UserSession.revoked_at.is_(None),
+            UserSession.expires_at > datetime.now(timezone.utc),
+        )
+        result = await self.session.execute(q)
+        return result.scalar_one_or_none()
+
+    async def get_by_previous_refresh_jti(self, jti: str) -> Optional[UserSession]:
+        q = select(UserSession).where(UserSession.previous_refresh_jti == jti)
+        result = await self.session.execute(q)
+        return result.scalar_one_or_none()
+
+    async def list_active_for_user(self, user_id: UUID | str) -> list[UserSession]:
+        if isinstance(user_id, str):
+            user_id = UUID(user_id)
+        q = (
+            select(UserSession)
+            .where(
+                UserSession.user_id == user_id,
+                UserSession.revoked_at.is_(None),
+                UserSession.expires_at > datetime.now(timezone.utc),
+            )
+            .order_by(UserSession.created_at.desc())
+        )
+        result = await self.session.execute(q)
+        return list(result.scalars().all())
+
+    async def revoke_session(self, session: UserSession) -> None:
+        session.revoked_at = datetime.now(timezone.utc)
+        self.session.add(session)
+        await self.session.flush()