first implementation

backend/routes/audit.py

@@ -0,0 +1,117 @@
+"""Audit routes for viewing action records."""
+from typing import Callable, TypeVar
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from sqlalchemy import select, func, desc
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from auth import require_permission
+from database import get_db
+from models import User, SumRecord, CounterRecord, Permission
+from schemas import (
+    CounterRecordResponse,
+    SumRecordResponse,
+    PaginatedCounterRecords,
+    PaginatedSumRecords,
+)
+
+
+router = APIRouter(prefix="/api/audit", tags=["audit"])
+
+R = TypeVar("R", bound=BaseModel)
+
+
+async def paginate_with_user_email(
+    db: AsyncSession,
+    model: type[SumRecord] | type[CounterRecord],
+    page: int,
+    per_page: int,
+    row_mapper: Callable[..., R],
+) -> tuple[list[R], int, int]:
+    """
+    Generic pagination helper for audit records that need user email.
+
+    Returns: (records, total, total_pages)
+    """
+    # Get total count
+    count_result = await db.execute(select(func.count(model.id)))
+    total = count_result.scalar() or 0
+    total_pages = (total + per_page - 1) // per_page if total > 0 else 1
+
+    # Get paginated records with user email
+    offset = (page - 1) * per_page
+    query = (
+        select(model, User.email)
+        .join(User, model.user_id == User.id)
+        .order_by(desc(model.created_at))
+        .offset(offset)
+        .limit(per_page)
+    )
+    result = await db.execute(query)
+    rows = result.all()
+
+    records: list[R] = [row_mapper(record, email) for record, email in rows]
+    return records, total, total_pages
+
+
+def _map_counter_record(record: CounterRecord, email: str) -> CounterRecordResponse:
+    return CounterRecordResponse(
+        id=record.id,
+        user_email=email,
+        value_before=record.value_before,
+        value_after=record.value_after,
+        created_at=record.created_at,
+    )
+
+
+def _map_sum_record(record: SumRecord, email: str) -> SumRecordResponse:
+    return SumRecordResponse(
+        id=record.id,
+        user_email=email,
+        a=record.a,
+        b=record.b,
+        result=record.result,
+        created_at=record.created_at,
+    )
+
+
+@router.get("/counter", response_model=PaginatedCounterRecords)
+async def get_counter_records(
+    page: int = Query(1, ge=1),
+    per_page: int = Query(10, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    _current_user: User = Depends(require_permission(Permission.VIEW_AUDIT)),
+) -> PaginatedCounterRecords:
+    """Get paginated counter action records."""
+    records, total, total_pages = await paginate_with_user_email(
+        db, CounterRecord, page, per_page, _map_counter_record
+    )
+    return PaginatedCounterRecords(
+        records=records,
+        total=total,
+        page=page,
+        per_page=per_page,
+        total_pages=total_pages,
+    )
+
+
+@router.get("/sum", response_model=PaginatedSumRecords)
+async def get_sum_records(
+    page: int = Query(1, ge=1),
+    per_page: int = Query(10, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    _current_user: User = Depends(require_permission(Permission.VIEW_AUDIT)),
+) -> PaginatedSumRecords:
+    """Get paginated sum action records."""
+    records, total, total_pages = await paginate_with_user_email(
+        db, SumRecord, page, per_page, _map_sum_record
+    )
+    return PaginatedSumRecords(
+        records=records,
+        total=total,
+        page=page,
+        per_page=per_page,
+        total_pages=total_pages,
+    )
+

backend/routes/auth.py

@@ -0,0 +1,135 @@
+"""Authentication routes for register, login, logout, and current user."""
+from datetime import datetime, UTC
+
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from auth import (
+    ACCESS_TOKEN_EXPIRE_MINUTES,
+    COOKIE_NAME,
+    get_password_hash,
+    get_user_by_email,
+    authenticate_user,
+    create_access_token,
+    get_current_user,
+    build_user_response,
+)
+from database import get_db
+from invite_utils import normalize_identifier
+from models import User, Role, ROLE_REGULAR, Invite, InviteStatus
+from schemas import UserLogin, UserResponse, RegisterWithInvite
+
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+
+
+def set_auth_cookie(response: Response, token: str) -> None:
+    """Set the authentication cookie on the response."""
+    response.set_cookie(
+        key=COOKIE_NAME,
+        value=token,
+        httponly=True,
+        secure=False,  # Set to True in production with HTTPS
+        samesite="lax",
+        max_age=ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+    )
+
+
+async def get_default_role(db: AsyncSession) -> Role | None:
+    """Get the default 'regular' role for new users."""
+    result = await db.execute(select(Role).where(Role.name == ROLE_REGULAR))
+    return result.scalar_one_or_none()
+
+
+@router.post("/register", response_model=UserResponse)
+async def register(
+    user_data: RegisterWithInvite,
+    response: Response,
+    db: AsyncSession = Depends(get_db),
+) -> UserResponse:
+    """Register a new user using an invite code."""
+    # Validate invite
+    normalized_identifier = normalize_identifier(user_data.invite_identifier)
+    result = await db.execute(
+        select(Invite).where(Invite.identifier == normalized_identifier)
+    )
+    invite = result.scalar_one_or_none()
+
+    # Return same error for not found, spent, and revoked to avoid information leakage
+    if not invite or invite.status in (InviteStatus.SPENT, InviteStatus.REVOKED):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid invite code",
+        )
+
+    # Check email not already taken
+    existing_user = await get_user_by_email(db, user_data.email)
+    if existing_user:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered",
+        )
+
+    # Create user with godfather
+    user = User(
+        email=user_data.email,
+        hashed_password=get_password_hash(user_data.password),
+        godfather_id=invite.godfather_id,
+    )
+
+    # Assign default role
+    default_role = await get_default_role(db)
+    if default_role:
+        user.roles.append(default_role)
+
+    db.add(user)
+    await db.flush()  # Get user ID
+
+    # Mark invite as spent
+    invite.status = InviteStatus.SPENT
+    invite.used_by_id = user.id
+    invite.spent_at = datetime.now(UTC)
+
+    await db.commit()
+    await db.refresh(user)
+
+    access_token = create_access_token(data={"sub": str(user.id)})
+    set_auth_cookie(response, access_token)
+    return await build_user_response(user, db)
+
+
+@router.post("/login", response_model=UserResponse)
+async def login(
+    user_data: UserLogin,
+    response: Response,
+    db: AsyncSession = Depends(get_db),
+) -> UserResponse:
+    """Authenticate a user and return their info with an auth cookie."""
+    user = await authenticate_user(db, user_data.email, user_data.password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect email or password",
+        )
+
+    access_token = create_access_token(data={"sub": str(user.id)})
+    set_auth_cookie(response, access_token)
+    return await build_user_response(user, db)
+
+
+@router.post("/logout")
+async def logout(response: Response) -> dict[str, bool]:
+    """Log out the current user by clearing their auth cookie."""
+    response.delete_cookie(key=COOKIE_NAME)
+    return {"ok": True}
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> UserResponse:
+    """Get the current authenticated user's info."""
+    return await build_user_response(current_user, db)
+

backend/routes/counter.py

@@ -0,0 +1,54 @@
+"""Counter routes."""
+from fastapi import APIRouter, Depends
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from auth import require_permission
+from database import get_db
+from models import Counter, User, CounterRecord, Permission
+
+
+router = APIRouter(prefix="/api/counter", tags=["counter"])
+
+
+async def get_or_create_counter(db: AsyncSession) -> Counter:
+    """Get the singleton counter, creating it if it doesn't exist."""
+    result = await db.execute(select(Counter).where(Counter.id == 1))
+    counter = result.scalar_one_or_none()
+    if not counter:
+        counter = Counter(id=1, value=0)
+        db.add(counter)
+        await db.commit()
+        await db.refresh(counter)
+    return counter
+
+
+@router.get("")
+async def get_counter(
+    db: AsyncSession = Depends(get_db),
+    _current_user: User = Depends(require_permission(Permission.VIEW_COUNTER)),
+) -> dict[str, int]:
+    """Get the current counter value."""
+    counter = await get_or_create_counter(db)
+    return {"value": counter.value}
+
+
+@router.post("/increment")
+async def increment_counter(
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(require_permission(Permission.INCREMENT_COUNTER)),
+) -> dict[str, int]:
+    """Increment the counter and record the action."""
+    counter = await get_or_create_counter(db)
+    value_before = counter.value
+    counter.value += 1
+
+    record = CounterRecord(
+        user_id=current_user.id,
+        value_before=value_before,
+        value_after=counter.value,
+    )
+    db.add(record)
+    await db.commit()
+    return {"value": counter.value}
+

backend/routes/invites.py

@@ -0,0 +1,247 @@
+"""Invite routes for public check, user invites, and admin management."""
+from datetime import datetime, UTC
+
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlalchemy import select, func, desc
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from auth import require_permission
+from database import get_db
+from invite_utils import generate_invite_identifier, normalize_identifier, is_valid_identifier_format
+from models import User, Invite, InviteStatus, Permission
+from schemas import (
+    InviteCheckResponse,
+    InviteCreate,
+    InviteResponse,
+    UserInviteResponse,
+    PaginatedInviteRecords,
+    AdminUserResponse,
+)
+
+
+router = APIRouter(tags=["invites"])
+
+MAX_INVITE_COLLISION_RETRIES = 3
+
+
+def build_invite_response(invite: Invite) -> InviteResponse:
+    """Build an InviteResponse from an Invite with loaded relationships."""
+    return InviteResponse(
+        id=invite.id,
+        identifier=invite.identifier,
+        godfather_id=invite.godfather_id,
+        godfather_email=invite.godfather.email,
+        status=invite.status.value,
+        used_by_id=invite.used_by_id,
+        used_by_email=invite.used_by.email if invite.used_by else None,
+        created_at=invite.created_at,
+        spent_at=invite.spent_at,
+        revoked_at=invite.revoked_at,
+    )
+
+
+# =============================================================================
+# Public Endpoints
+# =============================================================================
+
+@router.get("/api/invites/{identifier}/check", response_model=InviteCheckResponse)
+async def check_invite(
+    identifier: str,
+    db: AsyncSession = Depends(get_db),
+) -> InviteCheckResponse:
+    """Check if an invite is valid and can be used for signup."""
+    normalized = normalize_identifier(identifier)
+
+    # Validate format before querying database
+    if not is_valid_identifier_format(normalized):
+        return InviteCheckResponse(valid=False, error="Invalid invite code format")
+
+    result = await db.execute(
+        select(Invite).where(Invite.identifier == normalized)
+    )
+    invite = result.scalar_one_or_none()
+
+    # Return same error for not found, spent, and revoked to avoid information leakage
+    if not invite or invite.status in (InviteStatus.SPENT, InviteStatus.REVOKED):
+        return InviteCheckResponse(valid=False, error="Invite not found")
+
+    return InviteCheckResponse(valid=True, status=invite.status.value)
+
+
+# =============================================================================
+# User Endpoints (requires VIEW_OWN_INVITES permission)
+# =============================================================================
+
+@router.get("/api/invites", response_model=list[UserInviteResponse])
+async def get_my_invites(
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(require_permission(Permission.VIEW_OWN_INVITES)),
+) -> list[UserInviteResponse]:
+    """Get all invites owned by the current user."""
+    result = await db.execute(
+        select(Invite)
+        .where(Invite.godfather_id == current_user.id)
+        .order_by(desc(Invite.created_at))
+    )
+    invites = result.scalars().all()
+
+    # Use preloaded used_by relationship (selectin loading)
+    return [
+        UserInviteResponse(
+            id=invite.id,
+            identifier=invite.identifier,
+            status=invite.status.value,
+            used_by_email=invite.used_by.email if invite.used_by else None,
+            created_at=invite.created_at,
+            spent_at=invite.spent_at,
+        )
+        for invite in invites
+    ]
+
+
+# =============================================================================
+# Admin Endpoints (requires MANAGE_INVITES permission)
+# =============================================================================
+
+@router.get("/api/admin/users", response_model=list[AdminUserResponse])
+async def list_users_for_admin(
+    db: AsyncSession = Depends(get_db),
+    _current_user: User = Depends(require_permission(Permission.MANAGE_INVITES)),
+) -> list[AdminUserResponse]:
+    """List all users for admin dropdowns (invite creation, etc.)."""
+    result = await db.execute(select(User.id, User.email).order_by(User.email))
+    users = result.all()
+    return [AdminUserResponse(id=u.id, email=u.email) for u in users]
+
+
+@router.post("/api/admin/invites", response_model=InviteResponse)
+async def create_invite(
+    data: InviteCreate,
+    db: AsyncSession = Depends(get_db),
+    _current_user: User = Depends(require_permission(Permission.MANAGE_INVITES)),
+) -> InviteResponse:
+    """Create a new invite for a specified godfather user."""
+    # Validate godfather exists
+    result = await db.execute(
+        select(User.id).where(User.id == data.godfather_id)
+    )
+    godfather_id = result.scalar_one_or_none()
+    if not godfather_id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Godfather user not found",
+        )
+
+    # Try to create invite with retry on collision
+    invite: Invite | None = None
+    for attempt in range(MAX_INVITE_COLLISION_RETRIES):
+        identifier = generate_invite_identifier()
+        invite = Invite(
+            identifier=identifier,
+            godfather_id=godfather_id,
+            status=InviteStatus.READY,
+        )
+        db.add(invite)
+        try:
+            await db.commit()
+            await db.refresh(invite, ["godfather"])
+            break
+        except IntegrityError:
+            await db.rollback()
+            if attempt == MAX_INVITE_COLLISION_RETRIES - 1:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Failed to generate unique invite code. Please try again.",
+                )
+
+    if invite is None:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create invite",
+        )
+    return build_invite_response(invite)
+
+
+@router.get("/api/admin/invites", response_model=PaginatedInviteRecords)
+async def list_all_invites(
+    page: int = Query(1, ge=1),
+    per_page: int = Query(10, ge=1, le=100),
+    status_filter: str | None = Query(None, alias="status", description="Filter by status: ready, spent, revoked"),
+    godfather_id: int | None = Query(None, description="Filter by godfather user ID"),
+    db: AsyncSession = Depends(get_db),
+    _current_user: User = Depends(require_permission(Permission.MANAGE_INVITES)),
+) -> PaginatedInviteRecords:
+    """List all invites with optional filtering and pagination."""
+    # Build query
+    query = select(Invite)
+    count_query = select(func.count(Invite.id))
+
+    # Apply filters
+    if status_filter:
+        try:
+            status_enum = InviteStatus(status_filter)
+            query = query.where(Invite.status == status_enum)
+            count_query = count_query.where(Invite.status == status_enum)
+        except ValueError:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid status: {status_filter}. Must be ready, spent, or revoked",
+            )
+
+    if godfather_id:
+        query = query.where(Invite.godfather_id == godfather_id)
+        count_query = count_query.where(Invite.godfather_id == godfather_id)
+
+    # Get total count
+    count_result = await db.execute(count_query)
+    total = count_result.scalar() or 0
+    total_pages = (total + per_page - 1) // per_page if total > 0 else 1
+
+    # Get paginated invites (relationships loaded via selectin)
+    offset = (page - 1) * per_page
+    query = query.order_by(desc(Invite.created_at)).offset(offset).limit(per_page)
+    result = await db.execute(query)
+    invites = result.scalars().all()
+
+    # Build responses using preloaded relationships
+    records = [build_invite_response(invite) for invite in invites]
+
+    return PaginatedInviteRecords(
+        records=records,
+        total=total,
+        page=page,
+        per_page=per_page,
+        total_pages=total_pages,
+    )
+
+
+@router.post("/api/admin/invites/{invite_id}/revoke", response_model=InviteResponse)
+async def revoke_invite(
+    invite_id: int,
+    db: AsyncSession = Depends(get_db),
+    _current_user: User = Depends(require_permission(Permission.MANAGE_INVITES)),
+) -> InviteResponse:
+    """Revoke an invite. Only READY invites can be revoked."""
+    result = await db.execute(select(Invite).where(Invite.id == invite_id))
+    invite = result.scalar_one_or_none()
+
+    if not invite:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Invite not found",
+        )
+
+    if invite.status != InviteStatus.READY:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Cannot revoke invite with status '{invite.status.value}'. Only READY invites can be revoked.",
+        )
+
+    invite.status = InviteStatus.REVOKED
+    invite.revoked_at = datetime.now(UTC)
+    await db.commit()
+    await db.refresh(invite)
+
+    return build_invite_response(invite)
+

backend/routes/profile.py

@@ -0,0 +1,94 @@
+"""Profile routes for user contact details."""
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from auth import get_current_user
+from database import get_db
+from models import User, ROLE_REGULAR
+from schemas import ProfileResponse, ProfileUpdate
+from validation import validate_profile_fields
+
+
+router = APIRouter(prefix="/api/profile", tags=["profile"])
+
+
+async def require_regular_user(
+    current_user: User = Depends(get_current_user),
+) -> User:
+    """Dependency that requires the user to have the 'regular' role."""
+    if ROLE_REGULAR not in current_user.role_names:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Profile access is only available to regular users",
+        )
+    return current_user
+
+
+async def get_godfather_email(db: AsyncSession, godfather_id: int | None) -> str | None:
+    """Get the email of a godfather user by ID."""
+    if not godfather_id:
+        return None
+    result = await db.execute(
+        select(User.email).where(User.id == godfather_id)
+    )
+    return result.scalar_one_or_none()
+
+
+@router.get("", response_model=ProfileResponse)
+async def get_profile(
+    current_user: User = Depends(require_regular_user),
+    db: AsyncSession = Depends(get_db),
+) -> ProfileResponse:
+    """Get the current user's profile (contact details and godfather)."""
+    godfather_email = await get_godfather_email(db, current_user.godfather_id)
+
+    return ProfileResponse(
+        contact_email=current_user.contact_email,
+        telegram=current_user.telegram,
+        signal=current_user.signal,
+        nostr_npub=current_user.nostr_npub,
+        godfather_email=godfather_email,
+    )
+
+
+@router.put("", response_model=ProfileResponse)
+async def update_profile(
+    data: ProfileUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(require_regular_user),
+) -> ProfileResponse:
+    """Update the current user's profile (contact details)."""
+    # Validate all fields
+    errors = validate_profile_fields(
+        contact_email=data.contact_email,
+        telegram=data.telegram,
+        signal=data.signal,
+        nostr_npub=data.nostr_npub,
+    )
+
+    if errors:
+        raise HTTPException(
+            status_code=422,
+            detail={"field_errors": errors},
+        )
+
+    # Update fields
+    current_user.contact_email = data.contact_email
+    current_user.telegram = data.telegram
+    current_user.signal = data.signal
+    current_user.nostr_npub = data.nostr_npub
+
+    await db.commit()
+    await db.refresh(current_user)
+
+    godfather_email = await get_godfather_email(db, current_user.godfather_id)
+
+    return ProfileResponse(
+        contact_email=current_user.contact_email,
+        telegram=current_user.telegram,
+        signal=current_user.signal,
+        nostr_npub=current_user.nostr_npub,
+        godfather_email=godfather_email,
+    )
+

backend/routes/sum.py

@@ -0,0 +1,31 @@
+"""Sum calculation routes."""
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from auth import require_permission
+from database import get_db
+from models import User, SumRecord, Permission
+from schemas import SumRequest, SumResponse
+
+
+router = APIRouter(prefix="/api/sum", tags=["sum"])
+
+
+@router.post("", response_model=SumResponse)
+async def calculate_sum(
+    data: SumRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(require_permission(Permission.USE_SUM)),
+) -> SumResponse:
+    """Calculate the sum of two numbers and record it."""
+    result = data.a + data.b
+    record = SumRecord(
+        user_id=current_user.id,
+        a=data.a,
+        b=data.b,
+        result=result,
+    )
+    db.add(record)
+    await db.commit()
+    return SumResponse(a=data.a, b=data.b, result=result)
+