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

fastapi_forge/templates/with_rbac/tests/test_generator.py

@@ -0,0 +1,20 @@
+import ast
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_generated_rbac_project_structure():
+    assert (PROJECT_ROOT / "app/api/v1/roles/router.py").exists()
+    assert (PROJECT_ROOT / "app/api/v1/permissions/router.py").exists()
+    assert (PROJECT_ROOT / "app/db/models/permission.py").exists()
+    assert (PROJECT_ROOT / "Dockerfile").exists()
+    assert (PROJECT_ROOT / ".github/workflows/ci.yml").exists()
+
+
+def test_python_sources_compile():
+    for path in PROJECT_ROOT.rglob("*.py"):
+        source = path.read_text(encoding="utf-8")
+        ast.parse(source, filename=str(path))
+        compile(source, str(path), "exec")

fastapi_forge/templates/with_rbac/tests/test_permissions.py

@@ -0,0 +1,36 @@
+import pytest
+
+from app.core.dependencies import require_any_permission, require_permissions
+from app.core.exceptions import ForbiddenException
+
+
+@pytest.mark.asyncio
+async def test_require_permissions_accepts_all_required_permissions():
+    checker = require_permissions("users:read", "users:update")
+    payload = {"permissions": ["users:read", "users:update"]}
+
+    assert await checker(payload=payload) == payload
+
+
+@pytest.mark.asyncio
+async def test_require_permissions_rejects_missing_permission():
+    checker = require_permissions("users:update")
+
+    with pytest.raises(ForbiddenException):
+        await checker(payload={"permissions": ["users:read"]})
+
+
+@pytest.mark.asyncio
+async def test_require_any_permission_accepts_one_permission():
+    checker = require_any_permission("admin:write", "users:read")
+    payload = {"permissions": ["users:read"]}
+
+    assert await checker(payload=payload) == payload
+
+
+@pytest.mark.asyncio
+async def test_wildcard_bypasses_permission_checks():
+    checker = require_permissions("anything:write")
+    payload = {"permissions": ["*"]}
+
+    assert await checker(payload=payload) == payload

fastapi_forge/templates/with_rbac/tests/test_security.py

@@ -0,0 +1,68 @@
+from app.core.security import (
+    create_access_token,
+    create_refresh_token,
+    decode_token,
+    hash_password,
+    hash_opaque_token,
+    verify_password,
+)
+from app.api.v1.auth.schema import TokenResponse, UserResponse
+
+
+def test_password_hash_round_trip():
+    password = "StrongPassword123!"
+    hashed = hash_password(password)
+
+    assert hashed != password
+    assert verify_password(password, hashed)
+    assert not verify_password("wrong-password", hashed)
+
+
+def test_access_token_round_trip():
+    token, _ = create_access_token(
+        "user-123",
+        {"permissions": ["users:read"], "role": "ADMIN"},
+    )
+
+    payload = decode_token(token, expected_type="access")
+
+    assert payload["sub"] == "user-123"
+    assert payload["permissions"] == ["users:read"]
+    assert payload["role"] == "ADMIN"
+    assert payload["jti"]
+
+
+def test_refresh_token_round_trip():
+    token, _ = create_refresh_token("user-123")
+
+    payload = decode_token(token, expected_type="refresh")
+
+    assert payload["sub"] == "user-123"
+    assert payload["type"] == "refresh"
+
+
+def test_opaque_token_hash_is_deterministic_and_one_way():
+    token = "secret-reset-token"
+
+    assert hash_opaque_token(token) == hash_opaque_token(token)
+    assert hash_opaque_token(token) != token
+
+
+def test_refresh_token_is_excluded_from_serialized_login_response():
+    user = UserResponse(
+        id="user-123",
+        email="user@example.com",
+        username="user",
+        full_name="Example User",
+        is_active=True,
+        is_superuser=False,
+        is_verified=True,
+    )
+    response = TokenResponse(
+        access_token="access",
+        refresh_token="refresh-secret",
+        expires_in=1800,
+        user=user,
+    )
+
+    assert "refresh_token" not in response.model_dump()

fastapi_forge/templates/without_rbac/Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.12-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /build
+COPY requirements.txt .
+RUN python -m venv /opt/venv && /opt/venv/bin/pip install --upgrade pip && \
+    /opt/venv/bin/pip install -r requirements.txt
+
+FROM python:3.12-slim AS runtime
+
+ENV PATH="/opt/venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+RUN groupadd --system app && useradd --system --gid app --create-home app
+WORKDIR /app
+COPY --from=builder /opt/venv /opt/venv
+COPY --chown=app:app alembic alembic
+COPY --chown=app:app alembic.ini .
+COPY --chown=app:app app app
+COPY --chown=app:app scripts scripts
+
+USER app
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/health/live', timeout=3)"
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2", "--proxy-headers"]
+

fastapi_forge/templates/without_rbac/README.md

@@ -0,0 +1,106 @@
+# __PROJECT_NAME__
+
+A production-oriented FastAPI service with JWT authentication, PostgreSQL, Alembic, persistent audit logs, and superuser-based administration. This variant does not include RBAC.
+
+## Included
+
+- Access tokens plus cookie-only rotating refresh tokens, revocation, and sessions
+- Password reset and email verification
+- `is_superuser` authorization for administration endpoints
+- Structured logs, request IDs, CORS, trusted hosts, rate limiting, and security headers
+- Sync and async SQLAlchemy sessions with configurable pools
+- Liveness, readiness, and database health endpoints
+- Alembic migrations and an idempotent first-superuser seed command
+- A non-root Docker image, local Compose stack, tests, Ruff, and CI
+
+## Requirements
+
+Python 3.12+, PostgreSQL 14+, and optionally Docker with Compose v2.
+
+## Local setup
+
+Create the PostgreSQL database configured by `.env`, then:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements-dev.txt
+cp sample.env .env
+alembic upgrade head
+python scripts/seed_first_user.py \
+  --email admin@example.com \
+  --password 'ChangeMe123!' \
+  --full-name 'System Administrator'
+uvicorn app.main:app --reload
+```
+
+On Windows PowerShell, activate with `.venv\\Scripts\\Activate.ps1`. Development API documentation is at `http://localhost:8000/docs`.
+
+## Docker development
+
+```bash
+cp sample.env .env
+docker compose up --build
+```
+
+Seed the administrator from another terminal:
+
+```bash
+docker compose exec api python scripts/seed_first_user.py \
+  --email admin@example.com \
+  --password 'ChangeMe123!' \
+  --full-name 'System Administrator'
+```
+
+The Compose stack is for development; its credentials and bind mount are not production settings.
+
+## Configuration
+
+| Setting | Purpose |
+| --- | --- |
+| `APP_ENV` | Use `development`, `test`, or `production` |
+| `SECRET_KEY` | JWT signing key; production requires a unique 32+ character value |
+| `PG_*` | PostgreSQL connection and TLS mode |
+| `ALLOWED_HOSTS` | Comma-separated production hostnames |
+| `ALLOWED_ORIGINS` | Comma-separated browser origins |
+| `USE_REDIS`, `REDIS_URL` | Shared rate limits across replicas |
+| `LOG_TO_FILES`, `LOG_DIR` | Optional rotating files; stdout stays enabled |
+| `MAIL_*`, `FRONTEND_URL` | Email delivery and frontend links |
+
+Production startup rejects default/short secrets, wildcard hosts/origins, and non-TLS PostgreSQL modes.
+
+## Endpoints
+
+- `/api/v1/auth`, `/users`, and `/audit-logs`
+- `/api/v1/health/live`: process liveness
+- `/api/v1/health/ready`: database readiness; returns `503` when unavailable
+
+Docs and OpenAPI are disabled in production.
+
+The refresh token is stored only in a scoped HTTP-only cookie. Call
+`POST /api/v1/auth/refresh` with credentials enabled; it returns a new access token
+and rotates the refresh cookie without exposing that token to browser JavaScript.
+
+## Tests
+
+```bash
+pytest
+ruff check .
+```
+
+## Production checklist
+
+1. Build an immutable image: `docker build -t project-api:1.0.0 .`
+2. Supply secrets externally; configure explicit HTTPS origins and hosts.
+3. Use managed PostgreSQL with verified TLS and Redis for multi-replica rate limits.
+4. Run `alembic upgrade head` once as a release job before new replicas.
+5. Terminate TLS at a trusted proxy and centralize stdout/stderr logs.
+6. Monitor liveness/readiness; test backups, restores, rotation, and rollback.
+
+```bash
+docker run --rm --env-file .env project-api:1.0.0 alembic upgrade head
+docker run --rm --env-file .env -p 8000:8000 project-api:1.0.0
+```
+
+Do not run migrations concurrently from every application replica.

fastapi_forge/templates/without_rbac/_dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+.env
+.env.*
+.venv
+__pycache__
+*.py[cod]
+.pytest_cache
+.ruff_cache
+.coverage
+htmlcov
+logs
+uploads
+tests
+README.md
+

fastapi_forge/templates/without_rbac/_github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: pip install -r requirements-dev.txt
+      - run: ruff check .
+      - run: pytest
+

fastapi_forge/templates/without_rbac/_gitignore

@@ -0,0 +1,19 @@
+.env
+.env.*
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.idea/
+.vscode/
+uploads/*
+!uploads/.gitkeep
+
+DENTICON_DATA_FLOW.md
+
+
+logs/
+
+fastapi-forge

fastapi_forge/templates/without_rbac/alembic/README

@@ -0,0 +1 @@
+Generate migrations after model changes with: alembic revision --autogenerate -m "describe change"

fastapi_forge/templates/without_rbac/alembic/__init__.py

@@ -0,0 +1 @@
+

fastapi_forge/templates/without_rbac/alembic/env.py

@@ -0,0 +1,51 @@
+from logging.config import fileConfig
+
+from alembic import context
+from app.db.base import Base
+
+from app.core.config import settings
+from app.db.models import *
+
+config = context.config
+config.set_main_option("sqlalchemy.url", settings.postgres_url)
+
+if config.config_file_name:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline():
+    context.configure(
+        url=settings.postgres_url,
+        target_metadata=target_metadata,
+        include_schemas=True,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online():
+    from sqlalchemy import engine_from_config, pool
+
+    connectable = engine_from_config(
+        configuration=config.get_section(config.config_ini_section),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            include_schemas=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

fastapi_forge/templates/without_rbac/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

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

@@ -0,0 +1,125 @@
+"""Initial authentication and audit schema without RBAC."""
+
+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", "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",
+    )
+
+    for table_name in ("email_verification_tokens", "password_reset_tokens"):
+        op.create_table(
+            table_name,
+            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_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",
+    )
+
+
+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"),
+        ("users", "auth"),
+    ):
+        op.drop_table(table, schema=schema)
+    op.execute("DROP SCHEMA IF EXISTS app")
+    op.execute("DROP SCHEMA IF EXISTS auth")
+

fastapi_forge/templates/without_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/without_rbac/app/__init__.py

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,29 @@
+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.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"]),
+    (audit_logs_router, "/api/v1/audit-logs", ["Audit Logs"]),
+)
+
+
+def register_api_routes(app) -> None:
+    for route, prefix, tags in API_ROUTES:
+        app.include_router(route, prefix=prefix, tags=tags)
+
+
+for route, prefix, tags in API_ROUTES:
+    api_router.include_router(
+        route, prefix=prefix.removeprefix("/api/v1"), tags=tags
+    )
+
+router = api_router
+

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

@@ -0,0 +1 @@
+

fastapi_forge/templates/without_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