User Access Control and Permissions

The user access control system in this project is built on a two-tier permission model that distinguishes between account validity (is_active) and administrative authority (is_superuser). This design prioritizes simplicity and directness, using boolean flags within the User model to gate access to both API endpoints and frontend routes.

The Two-Tier Permission Model

The application implements access control through two primary flags on the user entity:

Active Status (is_active): This serves as the primary authentication gate. Even if a user provides valid credentials, the system denies access if this flag is false. In backend/app/api/deps.py, the get_current_user dependency enforces this check:

def get_current_user(session: SessionDep, token: TokenDep) -> User:
    # ... token validation logic ...
    user = session.get(User, token_data.sub)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    if not user.is_active:
        raise HTTPException(status_code=400, detail="Inactive user")
    return user

Superuser Privilege (is_superuser): This flag grants administrative access. It is checked by the get_current_active_superuser dependency, which builds upon get_current_user. This ensures that an administrator must be both authenticated and active before they can perform privileged operations.

Administrative Management and UI

Management of these permissions is centralized in the Admin section of the frontend. The AddUser and EditUser components provide the interface for superusers to toggle these flags for other accounts.

Form Validation and Data Handling

Both components use a shared FormData structure (inferred from a Zod schema) to ensure data integrity. When creating a user via AddUser, the is_active and is_superuser flags default to false, requiring an explicit action from an administrator to activate a new account or elevate its privileges.

In frontend/src/components/Admin/EditUser.tsx, the is_superuser and is_active fields are rendered as checkboxes:

<FormField
  control={form.control}
  name="is_superuser"
  render={({ field }) => (
    <FormItem className="flex items-center gap-3 space-y-0">
      <FormControl>
        <Checkbox
          checked={field.value}
          onCheckedChange={field.onChange}
        />
      </FormControl>
      <FormLabel className="font-normal">Is superuser?</FormLabel>
    </FormItem>
  )}
/>

The UsersService.updateUser method (generated in frontend/src/client/sdk.gen.ts) acts as the bridge, sending these updates to the PATCH /api/v1/users/{user_id} endpoint.

Frontend Route Protection

Access control is not limited to the backend. The frontend uses TanStack Router's beforeLoad hook to prevent non-superusers from even reaching administrative pages. In frontend/src/routes/_layout/admin.tsx, the route definition performs a pre-flight check:

export const Route = createFileRoute("/_layout/admin")({
  component: Admin,
  beforeLoad: async () => {
    const user = await UsersService.readUserMe()
    if (!user.is_superuser) {
      throw redirect({
        to: "/",
      })
    }
  },
})

This creates a cohesive security posture where the UI naturally hides or redirects away from unauthorized areas, while the API provides the final, authoritative enforcement.

Safety Constraints and Design Tradeoffs

The implementation includes specific safety measures to prevent system lockouts and accidental data loss:

Self-Deletion Prevention: The backend explicitly prevents superusers from deleting their own accounts. This is enforced in backend/app/api/routes/users.py within both the delete_user_me and delete_user functions:
```
if user == current_user:
    raise HTTPException(
        status_code=403, detail="Super users are not allowed to delete themselves"
    )
```
Initial Bootstrap: The system relies on environment variables (FIRST_SUPERUSER and FIRST_SUPERUSER_PASSWORD) to create the initial administrator during database initialization, solving the "chicken and egg" problem of account creation.

Tradeoffs

The choice of a flag-based system over a more complex Role-Based Access Control (RBAC) or Attribute-Based Access Control (ABAC) system reflects a design decision to favor maintainability for small-to-medium applications. While this model is less granular—for instance, you cannot easily create a "Moderator" role with a subset of admin permissions—it significantly reduces the complexity of the database schema and the logic required for permission checks throughout the codebase. For applications requiring more complex hierarchies, this system would serve as a foundation that could be extended by replacing the boolean flags with a more robust role entity.

The Two-Tier Permission Model​

Administrative Management and UI​

Form Validation and Data Handling​

Frontend Route Protection​

Safety Constraints and Design Tradeoffs​

Tradeoffs​