---
sessionId: session-260725-084752-m7a6
---

# Requirements

### Overview & Goals
The goal is to design `RequireServerPermission<const P: u64>` and `RequireChannelPermission<const P: u64>` Axum extractors using const generics with bitflags, and provide clear documentation and usage examples for developers adding permissions to view handlers.

### Scope
- **In Scope:**
  - Designing `RequireServerPermission<const PERM: u64>` and `RequireChannelPermission<const PERM: u64>` using const generics with `ServerPermission` and `ChannelPermission` bitflags.
  - Designing the path parameter extraction strategy for scope (extracting `server_id` or `channel_id` from request extensions / path parameters).
  - Handling superuser bypass (`is_superuser`) automatically.
  - Adding detailed documentation and usage examples (`src/http/permissions.rs` doc comments / guide).
- **Out of Scope:**
  - Modifying existing view handlers or database/repository schemas.

### Functional Requirements
- **FR1:** The extractor must support const generic bitflags.
- **FR2:** The extractor must automatically extract `CurrentUser`, check `is_superuser` for bypass, and fetch the required scope (`server_id` or `channel_id`).
- **FR3:** Unauthorized requests are rejected with `403 Forbidden`, unauthenticated with `401 Unauthorized`.

# Technical Design

### Current Implementation
- `CurrentUser` and `Superuser` extractors in `src/http/context.rs` implement `FromRequestParts`.
- `ServerPermission` and `ChannelPermission` are defined as `bitflags!` in `src/permissions.rs`.

### Key Decisions
- **Decision 1: Const Generics for Permission Extractors**
  - *Choice:* Use `RequireServerPermission<const PERM: u64>` and `RequireChannelPermission<const PERM: u64>`.
  - *Rationale:* Allows clean, declarative handler annotations.
- **Decision 2: Providing the Scope (`server_id` / `channel_id`)**
  - *Choice:* Extract path parameters (`server_id` / `channel_id` / `id`) dynamically via Axum path parameters / extensions.

### Proposed Changes
1. **Implement `src/http/permissions.rs`:**
   - Define `RequireServerPermission<const PERM: u64>` and `RequireChannelPermission<const PERM: u64>`.
   - Implement `FromRequestParts`.
   - Add extensive inline documentation and code examples showing how to annotate route handlers with `RequireServerPermission::<{ ServerPermission::MANAGE_SERVER.bits() }>` and `RequireChannelPermission::<{ ChannelPermission::READ_CHANNEL.bits() }>`.

### File Structure Changes
- **New File:** `src/http/permissions.rs`

# Testing

### Validation Approach
- Write unit/mock tests for the permission extractors.