oxspeak_server/.junie/plans/add-permission-policy-to-views.md

sessionId

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.