DEV Community: Bruce Dai

Frontend Simple Permission System Design and Implementation for Rustzen Admin

Bruce Dai — Sun, 24 Aug 2025 05:12:46 +0000

Overview

Rustzen Admin implements a comprehensive frontend permission control system built on React + TypeScript + Zustand technology stack. This system provides fine-grained permission control, including route-level permissions, component-level permissions, and operation-level permissions, ensuring users can only access and operate on functional modules they have permission for.

Core Architecture

1. Permission Data Structure

The system adopts a string-based permission code design with the format module:resource:action, for example:

system:user:create - User creation permission
system:user:edit - User editing permission
system:user:delete - User deletion permission
system:user:list - User list viewing permission

interface UserInfoResponse {
  id: number;
  username: string;
  realName?: string;
  avatarUrl?: string;
  permissions: string[]; // Permission code array
  isSystem: boolean; // Whether it is a system administrator
}

2. State Management - Zustand Store

Permission state is centrally managed through useAuthStore, using Zustand's persist middleware for state persistence:

interface AuthState {
  userInfo: Auth.UserInfoResponse | null;
  token: string | null;
  updateUserInfo: (params: Auth.UserInfoResponse) => void;
  updateToken: (params: string) => void;
  setAuth: (params: Auth.LoginResponse) => void;
  clearAuth: () => void;
  checkPermissions: (code: string) => boolean;
  checkMenuPermissions: (path: string) => boolean;
}

Permission Verification Mechanism

1. Permission Code Verification

The system implements an intelligent permission code matching, supports wildcards and hierarchical permissions, the specific implementation is as follows:

checkPermissions: (code: string) => {
  const permissions = get().userInfo?.permissions || [];
  if (permissions.length === 0) {
    return false;
  }
  if (permissions.includes("*")) {
    return true; // Super admin
  }
  if (permissions.includes(code)) {
    return true; // Exact match
  }
  // Hierarchical permission matching: system:user:* -> system:*
  const codeArr = code.split(":");
  for (let i = codeArr.length - 1; i > 0; i--) {
    const prefix = codeArr.slice(0, i).join(":") + ":*";
    if (permissions.includes(prefix)) {
      return true;
    }
  }
  return false;
};

2. Route Permission Verification

The system automatically converts route paths to permission codes for verification:

const formatPathCode = (pathname: string) => {
  const code = pathname.replace(/\//g, ":").slice(1);
  // Create page
  if (code.endsWith(":create")) {
    return code;
  }
  // Edit page, detail page
  if (code.endsWith(":edit") || code.endsWith(":detail")) {
    return code
      .split(":")
      .filter((s) => !/^\d+$/.test(s))
      .join(":");
  }
  // List page
  return `${code}:list`;
};

Permission Component System

1. AuthGuard - Route Guard

The AuthGuard component is responsible for route-level permission control, verifying permissions when users access pages:

export const AuthGuard: React.FC<AuthGuardProps> = ({ children }) => {
  const location = useLocation();
  const { token, updateUserInfo, checkMenuPermissions } = useAuthStore();

  // Redirect to login page if no token
  if (!token) {
    return <Navigate to="/login" state={{ from: location }} replace />;
  }

  // Check page permissions
  const isPermission = checkMenuPermissions(location.pathname);
  return isPermission ? children : <Navigate to="/403" replace />;
};

2. AuthWrap - Component-Level Permission Control

The AuthWrap component is used to control the display/hide of components:

export const AuthWrap: React.FC<AuthWrapProps> = ({
  code,
  children,
  hidden = false,
}) => {
  const isPermission = useAuthStore.getState().checkPermissions(code);
  if (isPermission && !hidden) {
    return children;
  }
  return null;
};

3. AuthConfirm - Operation-Level Permission Control

The AuthConfirm component is used for permission control of operations that require confirmation:

export const AuthConfirm: React.FC<AuthConfirmProps> = (props) => {
  const handleConfirm = () => {
    modalApi.confirm({
      title: props.title,
      content: props.description,
      onOk: props.onConfirm,
      onCancel: props.onCancel,
    });
  };

  return (
    <AuthWrap code={props.code} hidden={props.hidden}>
      <span onClick={handleConfirm} className={props.className}>
        {props.children}
      </span>
    </AuthWrap>
  );
};

Practical Application Examples

1. User Management Page Permission Control

export default function UserPage() {
  return (
    <ProTable<User.Item>
      // ... table configuration
      toolBarRender={() => [
        <AuthWrap code="system:user:create">
          <UserModalForm mode="create" onSuccess={handleSuccess}>
            <Button type="primary">Create User</Button>
          </UserModalForm>
        </AuthWrap>,
      ]}
      columns={[
        // ... other columns
        {
          title: "Actions",
          render: (_, entity) => (
            <Space size="middle">
              <AuthWrap code="system:user:detail">
                <UserModalForm mode="detail" initialValues={entity}>
                  <a>Detail</a>
                </UserModalForm>
              </AuthWrap>
              <MoreButton>
                <AuthWrap code="system:user:edit">
                  <UserModalForm mode="edit" initialValues={entity}>
                    <a>Edit</a>
                  </UserModalForm>
                </AuthWrap>
                <AuthConfirm
                  code="system:user:delete"
                  title="Are you sure you want to delete this user?"
                  onConfirm={handleDelete}
                >
                  Delete User
                </AuthConfirm>
              </MoreButton>
            </Space>
          ),
        },
      ]}
    />
  );
}

2. Dynamic Menu Generation

The system generates menus dynamically based on user permissions:

export const getMenuData = (): AppRouter[] => {
  const { checkMenuPermissions } = useAuthStore.getState();

  const getMenuList = (menuList: AppRouter[]): AppRouter[] => {
    return menuList
      .filter((item) => {
        if (!item.path) return false;
        if (item.children) return true;
        return checkMenuPermissions(item.path);
      })
      .map((item) => ({
        ...item,
        children: item.children ? getMenuList(item.children) : undefined,
      }))
      .filter((item) => {
        // Hide items without sub-menus
        if (item.children?.length === 0) {
          return false;
        }
        return true;
      });
  };
  return getMenuList(pageRoutes);
};

Permission System Features

1. Fine-Grained Control

Route-level permissions: Control page access
Component-level permissions: Control functional module display
Operation-level permissions: Control specific operation buttons

2. Intelligent Permission Matching

Support for exact permission code matching
Support for wildcard permissions (*)
Support for hierarchical permission inheritance (system:user:* → system:*)

3. User Experience Optimization

Automatically hide content without permissions to avoid interface confusion
Graceful degradation when permission verification fails
Support for permission state persistence

4. Permission Code Naming Conventions

Use module:resource:action format
Maintain naming consistency
Avoid overly complex permission hierarchies

5. Component Usage Recommendations

Scenario	Component	Example
Page access control	`AuthGuard`	Route-level permission verification
Functional module display	`AuthWrap`	Buttons, forms, and other components
Dangerous operation confirmation	`AuthConfirm`	Delete, export, and other operations

🎯 Summary: Simple Permission Control Solution

Core Benefits

Through this permission system, I achieved:

Improved development efficiency: Declarative permission control reduces repetitive code
Enhanced user experience: Automatically hide content without permissions for a cleaner interface
Reduced maintenance costs: Centralized permission logic management makes changes simpler
Enhanced security: Frontend and backend permission double verification

Technical Highlights

Intelligent permission matching: Supports exact matching, wildcard matching, and hierarchical inheritance
Component-based design: Three core components cover all permission scenarios
TypeScript support: Complete type definitions for excellent development experience
Performance optimization: Permission verification result caching to avoid repeated calculations

Applicable Scenarios

This permission system is particularly suitable for:

Small to medium-sized management systems: Relatively simple permission structure
Rapid development projects: Need to quickly build permission control
User experience priority: Focus on interface aesthetics and smooth interactions
Frontend-backend separation: Permission data interaction based on APIs

🧭 Final Thoughts

This permission system is my real practice in developing rustzen-admin, from initially hardcoding permissions to the final simple design. At the current project stage, simple permission control is sufficient to meet requirements. Unified permission standards between frontend and backend can avoid permission data inconsistency issues and facilitate future permission extensions.

If you're also troubled by permission control, try this solution. Perhaps it will help you make your permission system simpler and easier to maintain, just like it helped me.

📫 Related Resources:

My Rust Backend Journey: A Practical Guide from 0 to 1

Bruce Dai — Mon, 07 Jul 2025 11:01:30 +0000

📦 GitHub：https://github.com/idaibin/rustzen-admin

📝 Blog：https://idaibin.dev

I. What is Rustzen? Why this naming?

Rustzen is the name I chose for this project, meaning "Rust + Zen":
Rust brings performance and safety, Zen represents minimalism and order.

This is not just a combination of technology stacks, but my way of thinking about development experience:

Use minimal structure to express clearest intent
Use simplest path to build sustainable systems

Minimalism is not "doing less", but "just right". Every evolution of Rustzen is a question about "appropriate design + clear boundaries".

I started from Tauri + SQLite, gradually moved to Axum + SQLx, and continuously refined the current structure through evolution.
The starting point of this structure is a response to the following problems:

Early handler layer structure was loose, unclear responsibilities, routes and logic stacked, leading to maintenance difficulties;
Lack of clear data transmission specifications, logic duplication, increased testing costs;
In collaboration, due to unclear code structure, generated content was redundant and difficult to combine and reuse.

The emergence of Rustzen is a response to these problems—not pursuing complex frameworks, but seeking "just right" in structure.

II. Why adopt a three-layer architecture?

Why design it this way?

Clear structure is the foundation of maintainability. Three-layer separation allows each layer to focus only on its own responsibilities, reducing cognitive load.

Layer	Responsibility Description	Core Features
`router`	Route definition, permission binding, HTTP processing, intuitive functional entry	Router + Handler merged
`service`	Aggregate business logic, focus on behavior, encapsulate processing flow	Pure business logic, no framework dependency
`repo`	Database access, encapsulate SQL queries	First-line error handling

Directory Example:

features/
└── system/
    ├── mod.rs           // Module declaration
    ├── user/
    │   ├── mod.rs
    │   ├── router.rs    // Routes + handlers
    │   ├── service.rs   // Business logic
    │   ├── repo.rs      // Data access
    │   ├── entity.rs    // Database entities
    │   ├── dto.rs       // Request data transfer objects
    │   └── vo.rs        // Response view objects
    ├── role/
    └── menu/

III. Why split data models into entity/dto/vo?

Why design it this way?

entity/dto/vo separation avoids field redundancy and data leakage, facilitating evolution and collaboration.

Module	Description	Examples
`entity`	Maps database structure, used for SQLx queries	`UserWithRolesEntity`
`dto`	Receives frontend input parameters, field validation	`CreateUserDto`, `UserQueryDto`
`vo`	Returns fields needed for frontend display, secure desensitization	`UserListVo`, `UserDetailVo`

Use impl From<Entity> for VO to implement data conversion
Clear module responsibilities, facilitating AI and multi-person collaboration understanding and calling

IV. Authentication & Authorization: JWT + Server-side Permission Cache

System Overview:

Users first authenticate by logging in with their username and password. Upon successful authentication, the server issues a JWT containing only user identity information (such as user ID and username), not permissions.
All subsequent requests include the JWT; the server verifies the user's identity via the JWT.
User permission information is stored in a server-side local cache (permission cache) and is looked up and checked as needed.
The permission cache mechanism reduces database pressure and improves system response speed.

4.1 Middleware Architecture

Core Middleware Components

✅ JWT Authentication Middleware: Verifies the token and extracts user identity information
✅ Permission Verification Middleware: Looks up and checks permissions in the server-side cache using the user ID

Middleware Implementation Example

// JWT authentication middleware - only responsible for identity verification
pub async fn jwt_auth_middleware(
    mut request: Request,
    next: Next,
) -> Result<Response, AppError> {
    let token = extract_token_from_header(&request)?;
    // JWT contains only user identity information
    let user_claims = verify_jwt_claims(&token)?;
    request.extensions_mut().insert(CurrentUser { id: user_claims.user_id });
    Ok(next.run(request).await)
}

// Permission middleware - checks permissions in the server-side cache
pub async fn permission_middleware(
    request: Request,
    next: Next,
    permissions: PermissionsCheck,
) -> Result<Response, AppError> {
    let current_user = request.extensions().get::<CurrentUser>()
        .ok_or(ServiceError::InvalidToken)?;
    // Look up permissions in the server-side cache using user ID
    let has_permission = PermissionService::check_permissions(current_user.id, &permissions).await?;
    if !has_permission {
        return Err(ServiceError::PermissionDenied.into());
    }
    Ok(next.run(request).await)
}

Declarative Permission Usage Example

.route_with_permission(
    "/",
    get(get_user_list),
    PermissionsCheck::Any(vec!["system:*", "system:user:*", "system:user:list"]),
)

4.2 Permission Cache and Renewal Mechanism

Why design it this way?

Permission caching reduces database pressure, the renewal mechanism ensures an active user experience, and automatic expiration cleanup enhances security.

✅ Local memory cache: Reduces database queries
✅ Automatic cache expiration cleanup: 1-hour expiration, requires re-authorization
✅ Permission renewal mechanism: Each time the user info API is accessed, the user's permission cache is refreshed
✅ User status changes: When a user is disabled or forcibly logged out, the cache is immediately cleared
⚙️ Future extension: Plan to implement a refresh token mechanism for improved security

How it works:

When a user makes a request, the server first verifies the JWT and extracts basic user info (ID, username)
The server then looks up the user's permissions in the server-side cache using the user ID
Each time the user info API is called, the permission cache for that user is automatically refreshed
The JWT token itself does not yet support refresh; this is planned for future implementation

Permission Cache Implementation Example

// Permission cache manager
pub struct PermissionCacheManager {
    cache: Arc<RwLock<HashMap<i64, UserPermissionCache>>>,
}

impl PermissionService {
    pub async fn check_permissions(
        user_id: i64,
        permissions_check: &PermissionsCheck,
    ) -> Result<bool, ServiceError> {
        // Check if cache exists
        if let Some(cache) = PERMISSION_CACHE.get(user_id) {
            // Check if cache is expired
            if cache.is_expired() {
                PERMISSION_CACHE.remove(user_id);
                return Err(ServiceError::InvalidToken);
            }
            // Check permissions
            let has_permission = permissions_check.check(&cache.permissions);
            return Ok(has_permission);
        }
        Err(ServiceError::InvalidToken)
    }
}

// Permission cache renewal - implemented in AuthService
impl AuthService {
    // Get user login information
    #[tracing::instrument(name = "get_login_info", skip(pool))]
    pub async fn get_login_info(
        pool: &PgPool,
        user_id: i64,
    ) -> Result<UserInfoResponse, ServiceError> {
        // ...omitted...
        // Refresh user permission cache
        Self::refresh_user_permissions_cache(user_id, user.is_super_admin, permissions).await?;
        Ok(user_info)
    }

    pub async fn refresh_user_permissions_cache(
        user_id: i64,
        is_super_admin: bool,
        permissions: Vec<String>,
    ) -> Result<(), ServiceError> {
        if is_super_admin {
            // Super admin permission cache
            PermissionService::cache_user_permissions(user_id, vec!["*".to_string()]);
            return Ok(());
        }
        // Cache user permissions
        PermissionService::cache_user_permissions(user_id, permissions.clone());
        Ok(())
    }
}

4.3 Permission Granularity and Declaration

Permission granularity: The current project's permission granularity is sufficiently fine
Permission codes: Such as system:user:list, system:user:create, etc.
Wildcard support: system:* supports module-wide permissions

Note: The current project does not require more fine-grained permission control; the current granularity meets business requirements.

4.4 Performance Optimization Strategies

Connection pool management: Configurable connection limits and timeout settings
Prepared statements: Automatically handled through SQLx
Efficient pagination: Use offset/limit for pagination queries
Index optimization: Build indexes for commonly queried fields

V. Error Handling and Unified Response

Why design it this way?

Unified error types and response structures improve frontend-backend collaboration efficiency, facilitating AI automatic generation of API documentation and test cases.

ServiceError + AppResult unified error handling
ApiResponse unified response format

#[derive(Debug, thiserror::Error)]
pub enum ServiceError {
    #[error("User is disabled")]
    UserIsDisabled,
    #[error("Username already exists")]
    UsernameConflict,
    #[error("Database query failed")]
    DatabaseQueryFailed,
    #[error("{0} not found")]
    NotFound(String),
    #[error("Insufficient permissions")]
    PermissionDenied,
    #[error("Invalid or expired token")]
    InvalidToken,
    // ... more business error types
}

Error Conversion Mechanism

impl From<ServiceError> for AppError {
    fn from(err: ServiceError) -> Self {
        let (status, code, message) = match err {
            ServiceError::NotFound(resource) => (
                StatusCode::NOT_FOUND,
                10001,
                format!("{} not found", resource),
            ),
            ServiceError::UsernameConflict => (
                StatusCode::CONFLICT,
                10201,
                "Username already exists".to_string(),
            ),
            ServiceError::DatabaseQueryFailed => (
                StatusCode::INTERNAL_SERVER_ERROR,
                20001,
                "Service temporarily unavailable, please try again later".to_string(),
            ),
            ServiceError::InvalidToken => (
                StatusCode::UNAUTHORIZED,
                30000,
                "Invalid or expired token, please login again".to_string(),
            ),
            // ... complete error mapping
        };
        AppError((status, code, message))
    }
}

All processing logic uniformly returns AppResult<T>, AppResult has built-in Json<ApiResponse<T>>, simplifying return types
Interface layer directly .await? destructures errors, no redundant processing needed
Error response structure is unified:

VI. Response Format: Two Schemes Unified Processing

Scheme One: Simple Response Format

// Single object or non-paginated response
ApiResponse::success(data)

// Response JSON:
{
  "code": 0,
  "message": "Success",
  "data": {
    "id": 1,
    "username": "admin"
  }
}

Scheme Two: Standard Pagination Format

// Paginated list interface
ApiResponse::page(data, total)

// Response JSON:
{
  "code": 0,
  "message": "Success",
  "data": [...],
  "total": 100
}

// In router.rs
pub async fn get_user_list(...) -> AppResult<Vec<UserListVo>> {
    let (users, total) = UserService::get_user_list(&pool, query).await?;
    Ok(ApiResponse::page(users, total))  // Pagination format
}

pub async fn get_user_by_id(...) -> AppResult<UserDetailVo> {
    let user = UserService::get_user_by_id(&pool, id).await?;
    Ok(ApiResponse::success(user))  // Simple format
}

VII. Database Migration Strategy: Zen-Style Numbering System

Type	Example Number	Description
Table Structure	`100100` ~ `100500`	Users, roles, menus, etc. basic tables
Foreign Keys / Triggers	`100800`, `100900`	Table constraints, log archiving
Views	`1070xx`	Aggregate views, such as user permissions
Functions	`1080xx`	Query encapsulation, login, permission calculation
Data Seeds	`1090xx`	Initialize users, menus, dictionary data, etc.

✅ Modular, traceable, excellent AI maintainability
⚠️ Many files, consider merging files when reaching milestones later
Each file contains a single entity (view, function, or seed), conforming to Zen style

VIII. Module Dependency Relationship Management

Clear Module Boundaries

// In system/mod.rs
pub fn system_routes() -> Router<PgPool> {
    Router::new()
        .nest("/users", user_routes())
        .nest("/menus", menu_routes())
        .nest("/roles", role_routes())
        .nest("/dicts", dict_routes())
        .nest("/logs", log_routes())
}

Facing complexity, we choose clarity;
Facing redundancy, we choose necessity;
Facing chaos, we choose Zen.

Rustzen is not a framework, but a way of thinking.
I hope it's written not just for the current me, but also for those of you who are also on the road in the future.

IX. AI-Assisted Programming: The More Zen the Structure, the Higher the Efficiency

Clear structure allows AI to automatically generate modules (router/dto/service)
Unified naming, clear logic, facilitating prompt generation and batch refactoring
Clear module responsibilities, reducing error and rewrite costs
Log content consistent with function names, facilitating AI understanding and debugging

X. Conclusion: Rust + Zen, Minimalism is Not Less, But Just Right

Rustzen is an architectural exploration from chaos to order.

Minimalism is not about "doing less", but about simple design, just right; it provides a clear foundation for AI collaboration, teamwork, and future expansion.

Architecture Advantages Summary

✅ Simplicity: Three-layer architecture reduces cognitive load
✅ AI-Friendly: Clear separation of concerns, facilitating AI assistance
✅ Type Safety: Strong type system, compile-time guarantees
✅ High Performance: Caching reduces database load, permission renewal mechanism
✅ Maintainability: Single responsibility principle, clear error handling
✅ Security: Proper cache expiration mechanism, requires re-authorization when cache expires

Future Improvement Directions

🔄 Token Mechanism: Implement refresh token support
🔄 Complete Feature Modules: After initial release, complete feature modules based on feedback
🔄 Monitoring Metrics: Add performance monitoring and metric collection
🔄 Cache Optimization: Consider Redis distributed caching for production environment
🔄 Documentation Improvement: More comprehensive documentation, introducing related design and usage instructions
🔄 Log Optimization: Optimize log format

XI. Closing Message: A Growing Project, Welcome Resonance

Rustzen is the crystallization of my practice from frontend to backend exploration. It's not an endpoint, but a path to order and clarity.

May every developer find their own balance and direction in the pursuit of "just right".

Welcome feedback and co-creation, let Rustzen become more developers' choice of "just right"!

📦 Project source code: https://github.com/idaibin/rustzen-admin
📝 More hands-on articles: https://idaibin.dev

Why I Choose Rust to Build a Full-Stack Admin System

Bruce Dai — Sun, 29 Jun 2025 13:01:19 +0000

I'm originally a front-end developer, mainly working with React and TypeScript.

Over time, I've also explored Node.js, Next.js, and Bun for building admin dashboards.

Recently, I started building a Rust-based full-stack project called rustzen-admin.

This post shares my personal journey as a front-end dev trying Rust for the first time — from using Tauri to building a backend API with Axum, and eventually a complete admin system.

🧠 How It Started: From Vite to Tauri

My Rust journey started passively.

I noticed Rust was used in performance-critical tools like Vite plugins.
Later I discovered Tauri, a lightweight Rust-based framework for desktop apps — a modern alternative to Electron.

When I had to build a small PC tool, Electron felt too heavy. So I gave Tauri a try.

The frontend setup was familiar, but once I saw the backend Rust code — I was completely lost.

🤖 Learning by Doing (with AI)

I didn't sit down and study Rust from scratch.

✅ I initialized a Tauri project → got stuck → asked ChatGPT → tweaked code → got stuck again → repeated until it worked.

Initially I just handled some local file storage.

Then I decided to persist data with SQLite, introduced sqlx, explored async functions, error handling, and eventually modularized the project.

Rust's ownership, type system, and syntax were tough at first.

But with real use cases and help from AI, I started to understand the logic and write more idiomatic code.

🛠️ Why Not Java / Node / Bun?

Before diving into Rust, I took time to evaluate some common backend choices:

Tech Stack	Pros	Cons
Java	Stable, mature, widely used in companies	Verbose, slower startup, heavyweight setup
Node.js	Huge ecosystem, easy to learn, fast to build	Weak typing, limited performance, heavy runtime
Bun	Fast startup, lightweight toolchain	Small community, early-stage ecosystem
Rust	💪 Native performance, safe, easy to deploy	Steeper learning curve

I don't work on massive enterprise systems. I just wanted a backend that is reliable, lightweight, and easy to maintain.

That's why I chose Rust: build once, ship a binary, no runtime, no Docker, no surprises.

🏗️ rustzen-admin: A Full-Stack Template in Rust + React

To organize my learnings, I started building rustzen-admin,

a clean full-stack admin system powered by Rust and React — ideal for private deployment, lightweight dashboards, or internal tools.

Tech Stack Overview:

Backend: Rust + Axum + sqlx + RBAC permissions + JWT auth
Frontend: Vite + React + TailwindCSS + Zustand
Tooling: dotenv for config, tracing for logs, argon2 for password hashing
Deployment: Compiles into a single binary — no Docker, no Node runtime needed

✅ What's Done So Far

Here's what I've implemented so far:

User registration, login, and JWT-based authentication
Role-based permission system with RBAC
Clean RESTful API structure and consistent error handling
Modular backend architecture with service separation
Frontend integration with TailwindUI and Zustand

The project was built completely by myself, learning as I go — using AI and community docs whenever I got stuck.

✨ Why I'll Continue Using Rust

Rust isn't the easiest language to learn, but the trade-offs are worth it.

What I love most about Rust:

Confidence in code: The type system prevents so many bugs at compile time
Deploy simplicity: One file, drop it on the server, and you're good to go
Memory safety: No GC, no leaks, great performance
Cross-platform options: With Tauri, I can even ship desktop versions of the same backend

As a solo developer, these qualities let me build faster, deploy with ease, and focus more on product logic — not devops or runtime debugging.

📚 Resources

The Rust Book
Rust by Example
Project Repo: rustzen-admin
More posts on my blog: idaibin.dev

🧭 Final Thoughts

I'm not a backend engineer. I'm not a systems programmer.

I'm just a front-end developer trying to build a clean, reliable admin system.

Rust didn't make things faster at first — it made me think. But in return, it gave me confidence, clarity, and performance.

This post isn't about being an expert — it's about what it's like to start Rust as a real beginner.

If you're a front-end dev curious about Rust, start small.

Try Tauri. Build a CLI. Wrap a simple API. And maybe, like me, you'll stay.

📫 Follow along — I'll be sharing more about Rust + React full-stack development in future posts.

rustzen-admin: Complete Declarative Permission System Architecture for Axum Backends

Bruce Dai — Thu, 26 Jun 2025 06:55:50 +0000

This article introduces a modern permission system design and implementation based on the Rust Axum framework, focusing on how to build a high-performance, maintainable permission control system through declarative APIs, intelligent caching, and middleware architecture.

I. Introduction: Why Design a Unified Permission System?

In modern web application development, permission control is an unavoidable core requirement. As business complexity grows, we face the following challenges:

🔍 Pain Points of Traditional Permission Control

Scattered Permission Checks: Each API endpoint requires manual permission checking code

// ❌ Traditional approach: Every handler needs repeated permission checks
async fn user_list_handler(current_user: CurrentUser) -> Result<Json<Vec<User>>, AppError> {
    if !current_user.has_permission("system:user:list") {
        return Err(AppError::PermissionDenied);
    }
    // Business logic...
}

Maintenance Difficulties: Permission logic scattered everywhere, hard to manage and debug uniformly

Performance Issues: Every request requires database queries to fetch permission information

Security Risks: Easy to miss permission checks or have inconsistent permission logic

🎯 Our Solution

Design a centralized, declarative, high-performance permission system that implements:

✅ Declare permission requirements during route registration
✅ Unified permission validation through middleware
✅ Intelligent caching to reduce database queries
✅ Flexible permission combination logic

II. Design Goals and Principles

🎯 Core Goals of Permission System

Centralized Permission Declaration: Permission binding completed during route registration phase, clear at a glance
Unified Middleware Validation: All permission validation logic centralized in middleware layer
Automatic User Information Injection: No need for manual user identity handling
Cache Optimization: Avoid repeated queries, support intelligent refresh

✅ Design Principles

Minimal Coupling: Complete separation of Authentication and Authorization

// Authentication middleware: Only responsible for identity verification
pub async fn auth_middleware(/* ... */) -> Result<Response, AppError>

// Permission middleware: Only responsible for permission checking
async fn permission_middleware(/* ... */) -> Result<Response, AppError>

Extensibility: Support single permission, any permission, all permissions and other combination modes

High Performance: In-memory caching + expiration refresh, minimize database access

Clean and Readable: Developer-friendly declarative API

III. Permission System Architecture Overview

🔄 Complete Request Processing Flow

graph TD
    A[HTTP Request] --> B[Auth Middleware]
    B --> C{JWT Verification}
    C -->|Failed| D[401 Unauthorized]
    C -->|Success| E[Inject CurrentUser]
    E --> F[Permission Middleware]
    F --> G{Permission Cache Check}
    G -->|Cache Hit| H[Permission Validation]
    G -->|Cache Miss| I[Database Query]
    I --> J[Update Cache]
    J --> H
    H -->|Insufficient Permission| K[403 Forbidden]
    H -->|Permission Granted| L[Execute Business Handler]

🏗️ Module Architecture Design

Module	File	Responsibility
JWT Authentication	`core/jwt.rs`	Token generation, verification, Claims parsing
User Extraction	`auth/extractor.rs`	CurrentUser structure definition and extraction logic
Auth Middleware	`auth/middleware.rs`	JWT verification, user information injection
Permission Cache	`auth/permission.rs`	Permission cache management, permission validation logic
Router Extension	`common/router_ext.rs`	Declarative permission binding API

IV. Core Module Details

4.1 JWT Authentication Module

Design Philosophy: JWT only handles identity recognition, does not carry permission information

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Claims {
    pub user_id: i64,      // User unique identifier
    pub username: String,  // Username
    pub exp: usize,        // Expiration time
    pub iat: usize,        // Issued at time
}

Key Features:

🔧 Environment variable configuration for secret key and expiration time
🛡️ Default value warnings to avoid production environment security risks
⚡ High-performance token verification

pub fn verify_token(token: &str) -> Result<Claims, jsonwebtoken::errors::Error> {
    let validation = Validation::new(Algorithm::HS256);
    let token_data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(JWT_CONFIG.secret.as_bytes()),
        &validation,
    )?;
    Ok(token_data.claims)
}

4.2 User Information Extractor `CurrentUser`

Design Highlight: Implements Axum's FromRequestParts, supports dependency injection

📋 CurrentUser vs Claims Semantic Differences

Concept	Purpose	Lifecycle	Information Contained
Claims	JWT Token payload data	Token validity period	Basic identity information
CurrentUser	Business layer user abstraction	Single request	Verified user information

// Claims: Raw data after JWT parsing, only used for authentication
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Claims {
    pub user_id: i64,
    pub username: String,
    pub exp: usize,
    pub iat: usize,
}

// CurrentUser: Unified business layer user structure for dependency injection
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CurrentUser {
    pub user_id: i64,
    pub username: String,
}

// 🎯 Key: Implement FromRequestParts for automatic extraction
impl<S> FromRequestParts<S> for CurrentUser
where S: Send + Sync,
{
    type Rejection = AppError;

    fn from_request_parts(/* ... */) -> impl Future<Output = Result<Self, Self::Rejection>> {
        // Get user information from request extensions
        // Data comes from authentication middleware parsing Claims and injecting information
    }
}

Design Principles:

Claims only for authentication: JWT parsing followed by immediate conversion, not used directly in business code
CurrentUser is unified business structure: All handlers use uniformly, ensuring type safety

Usage:

// ✅ Extract current user information
async fn user_profile_handler(current_user: CurrentUser) -> Json<UserProfile> {
    // current_user automatically injected, contains user_id and username
}

// 🔧 Uniformly use CurrentUser to extract user information
async fn get_user_info_handler(
    current_user: CurrentUser,  // Automatically inject current user information
    State(pool): State<PgPool>,
) -> AppResult<Json<ApiResponse<UserInfoResponse>>> {
    let user_info = AuthService::get_user_info(&pool, current_user.user_id, &current_user.username).await?;
    Ok(ApiResponse::success(user_info))
}

4.3 Intelligent Permission Caching Mechanism

Core Design: In-memory cache + expiration refresh + thread safety

/// Permission cache entry with expiration time
#[derive(Debug, Clone)]
pub struct UserPermissionCache {
    pub permissions: HashSet<String>,  // User permission set
    pub cached_at: DateTime<Utc>,      // Cache time
}

/// Global cache manager, thread-safe
pub struct PermissionCacheManager {
    cache: Arc<RwLock<HashMap<i64, UserPermissionCache>>>,
}

Intelligent Refresh Strategy:

pub async fn get_cached_permissions(
    pool: &PgPool,
    user_id: i64,
) -> Result<Option<UserPermissionCache>, ServiceError> {
    if let Some(cache) = PERMISSION_CACHE.get(user_id) {
        if cache.is_expired() {
            // 🔄 Cache expired, automatically refresh from database
            let new_cache = Self::load_user_permissions_from_db(pool, user_id).await?;
            return Ok(Some(new_cache));
        }
        return Ok(Some(cache));
    }
    Ok(None)
}

Performance Optimization:

⚡ Read-write lock for high-concurrency access
🕐 1-hour cache expiration time, balancing performance and real-time
🔄 Automatic reload on cache expiration, transparent to users

V. Declarative Route Permission Binding Design

5.1 RouterExt Trait Design

Core Innovation: Extend Axum Router to support permission declaration

pub trait RouterExt<S> {
    fn route_with_permission(
        self,
        path: &str,
        method_router: MethodRouter<S>,
        permissions_check: PermissionsCheck,  // 🎯 Core: Permission check configuration
    ) -> Self;
}

Implementation Principle:

impl RouterExt<PgPool> for Router<PgPool> {
    fn route_with_permission(self, path: &str, method_router: MethodRouter<PgPool>, permissions_check: PermissionsCheck) -> Self {
        self.route(
            path,
            method_router.layer(axum::middleware::from_fn(move |req: Request, next: Next| {
                let permissions_check = permissions_check.clone();
                async move { permission_middleware(req, next, permissions_check).await }
            })),
        )
    }
}

5.2 Flexible Permission Check Modes

PermissionsCheck Enum: Support multiple permission combination logic

#[derive(Debug, Clone)]
pub enum PermissionsCheck {
    Single(&'static str),           // Single permission
    Any(Vec<&'static str>),        // Any permission (OR logic)
    All(Vec<&'static str>),        // All permissions (AND logic)
}

Usage Examples:

// 🔹 Single permission check
router.route_with_permission(
    "/system/users",
    get(user_list_handler),
    PermissionsCheck::Single("system:user:list")
)

// 🔹 Any permission check (admin or user admin can access)
router.route_with_permission(
    "/system/users",
    post(create_user_handler),
    PermissionsCheck::Any(vec!["admin:all", "system:user:create"])
)

// 🔹 All permissions check (requires delete permission AND confirm permission)
router.route_with_permission(
    "/system/users/{id}",
    delete(delete_user_handler),
    PermissionsCheck::All(vec!["system:user:delete", "system:confirm"])
)

5.3 Permission Middleware Core Logic

Unified Permission Validation Flow:

async fn permission_middleware(
    request: Request,
    next: Next,
    permissions_check: PermissionsCheck,
) -> Result<Response, AppError> {
    // 1️⃣ Get current user (injected by auth middleware)
    let current_user = request.extensions().get::<CurrentUser>()
        .ok_or(AppError::from(ServiceError::InvalidCredentials))?;

    // 2️⃣ Get database connection pool
    let pool = request.extensions().get::<PgPool>()
        .ok_or(AppError::from(ServiceError::DatabaseQueryFailed))?;

    // 3️⃣ Check permissions (cache first)
    let has_permission = PermissionService::check_permissions(
        &pool,
        current_user.user_id,
        &permissions_check
    ).await?;

    // 4️⃣ Deny access if insufficient permissions
    if !has_permission {
        return Err(AppError::from(ServiceError::PermissionDenied));
    }

    // 5️⃣ Permission granted, continue execution
    Ok(next.run(request).await)
}

VI. Permission Cache and JWT Collaboration Mechanism

6.1 Dual-Layer Cache Design

Cache Type	Storage Location	Expiration Time	Refresh Mechanism	Purpose
JWT Token	Client	1-2 hours	Re-login on expiration	Identity authentication
Permission Cache	Server memory	1 hour	Auto refresh	Permission validation

6.2 Cache Collaboration Flow

Cache Permissions on Login:

// Login triggers permission caching
pub async fn login(pool: &PgPool, request: LoginRequest) -> Result<LoginResponse, ServiceError> {
    let user = Self::verify_login(pool, &request.username, &request.password).await?;
    let token = jwt::generate_token(user.id, &user.username)?;

    // Getting user info automatically caches permissions
    let user_info = Self::get_user_info(pool, user.id, &user.username).await?;
    Ok(LoginResponse { token, user_info })
}

// 🎯 Key location for permission caching
pub async fn get_user_info(pool: &PgPool, user_id: i64, username: &str) -> Result<UserInfoResponse, ServiceError> {
    // Query user permissions
    let permissions = UserRepository::get_user_permissions(pool, user_id).await?;

    // 🎯 Cache permissions to memory (1 hour validity)
    PermissionService::cache_user_permissions(user_id, permissions);

    // Return user info...
}

Cache Strategy for Permission Checking:

pub async fn check_permissions(
    pool: &PgPool,
    user_id: i64,
    permissions_check: &PermissionsCheck,
) -> Result<bool, ServiceError> {
    // 🔍 Try to get permissions from cache
    if let Some(cache) = Self::get_cached_permissions(pool, user_id).await? {
        return Ok(permissions_check.check(&cache.permissions));
    }

    // 🚫 Cache miss, require re-authentication
    // Design rationale: This shouldn't happen in normal business flow,
    // if it occurs, it indicates system anomaly, deny access for security
    // Supports logout after user prohibition/deletion
    Err(ServiceError::InvalidCredentials)
}

6.3 Cache Invalidation and Security

Key Scenarios for Active Cache Clearing:

// 1️⃣ Clear permission cache on logout
async fn logout_handler(current_user: CurrentUser) -> AppResult<Json<ApiResponse<()>>> {
    PermissionService::clear_user_cache(current_user.user_id);
    Ok(ApiResponse::success(()))
}

// 2️⃣ Clear cache when deleting user
pub async fn delete_user(pool: &PgPool, id: i64) -> Result<(), ServiceError> {
    let deleted = UserRepository::soft_delete(pool, id).await?;
    if !deleted {
        return Err(ServiceError::NotFound("User not found".to_string()));
    }

    // 🎯 Key: Clear user's permission cache when deleting user
    PermissionService::clear_user_cache(id);
    tracing::info!("Deleted user {} and cleared associated cache", id);

    Ok(())
}

// 3️⃣ Clear cache when user roles change
pub async fn update_user(/* ... */) -> Result<UserResponse, ServiceError> {
    // When updating user roles
    if let Some(role_ids) = request.role_ids {
        UserRepository::set_user_roles(pool, updated_user.id, &role_ids).await?;

        // 🎯 Clear permission cache after role change, force reload
        PermissionService::clear_user_cache(updated_user.id);
        tracing::info!("Updated user {} roles and cleared permission cache", updated_user.id);
    }

    // When user status changes (especially disabling user)
    if let Some(new_status) = request.status {
        if new_status != user.status {
            PermissionService::clear_user_cache(updated_user.id);
            tracing::info!("Updated user {} status and cleared permission cache", updated_user.id);
        }
    }
}

Cache Security Strategy:

✅ User Deletion: Immediately clear permission cache to prevent permission residue of deleted users
✅ Role Changes: Clear cache after user role modification to ensure new permissions take effect
✅ Status Changes: Clear cache after user disabling to prevent disabled users from continued access
✅ Active Logout: Clear cache on user logout to enhance security

VII. Practical Usage Examples

7.1 System Management Module Route Configuration

pub fn system_routes() -> Router<PgPool> {
    Router::new()
        // User management
        .route_with_permission(
            "/users",
            get(user_list_handler),
            PermissionsCheck::Single("system:user:list")
        )
        .route_with_permission(
            "/users",
            post(create_user_handler),
            PermissionsCheck::Single("system:user:create")
        )
        .route_with_permission(
            "/users/{id}",
            put(update_user_handler),
            PermissionsCheck::Single("system:user:update")
        )
        .route_with_permission(
            "/users/{id}",
            delete(delete_user_handler),
            PermissionsCheck::All(vec!["system:user:delete", "system:confirm"])
        )

        // Role management
        .route_with_permission(
            "/roles",
            get(role_list_handler),
            PermissionsCheck::Any(vec!["system:role:list", "admin:all"])
        )
}

7.2 Handler Implementation

// ✅ Handler focuses on business logic, no need to worry about permission checks
async fn user_list_handler(
    current_user: CurrentUser,  // Automatically injected current user
    State(pool): State<PgPool>,
) -> AppResult<Json<ApiResponse<Vec<UserResponse>>>> {
    // Permission already checked at middleware layer, handle business logic directly here
    let users = UserService::list_users(&pool).await?;
    Ok(ApiResponse::success(users))
}

async fn delete_user_handler(
    current_user: CurrentUser,
    State(pool): State<PgPool>,
    Path(user_id): Path<i64>,
) -> AppResult<Json<ApiResponse<()>>> {
    // Permission check: requires system:user:delete AND system:confirm
    // Already declared at route layer, middleware handles automatically
    UserService::delete_user(&pool, user_id).await?;
    Ok(ApiResponse::success(()))
}

VIII. Summary

🎯 Multiple Benefits from Core Design

Declarative Permission Binding Design:

✅ Development Efficiency: Reduce repetitive code writing
✅ Maintainability: Permission requirements clear at a glance
✅ Extensibility: Support flexible permission combinations

Intelligent Caching Mechanism:

✅ Performance Optimization: Reduce database queries, improve response speed
✅ Security Assurance: Support active clearing, permission changes take effect immediately
✅ Extensibility: Can be replaced with external caches like Redis

Unified Middleware Processing:

✅ Development Efficiency: Automatic user information injection
✅ Security: Centralized permission control, avoid omissions
✅ Maintainability: Unified permission logic management

📊 Overall Effect

Design Feature	Development Efficiency	Performance Optimization	Security Assurance	Maintainability	Extensibility
Declarative API	✅	-	✅	✅	✅
Intelligent Cache	-	✅	✅	-	✅
Unified Middleware	✅	-	✅	✅	-
Modular Design	✅	-	-	✅	✅

Complete Integration Example: main.rs

rustzen-admin: Authentication Security Upgrade - From bcrypt to Argon2

Bruce Dai — Mon, 23 Jun 2025 16:50:38 +0000

JWT Middleware Design + Argon2 Password Security + Complete Authentication Flow Implementation

🎯 Introduction: Why Upgrade Password Security?

When building enterprise-level management systems, authentication security is often the first line of defense that developers encounter. However, many projects still rely on older password hashing algorithms like bcrypt, which, while secure, may not represent the current best practices for password security.

In the rustzen-admin project, I recently went through a comprehensive authentication security upgrade. To be honest, I was initially hesitant about migrating from bcrypt to Argon2 - after all, bcrypt was working perfectly fine, so why fix what isn't broken? But after diving deep into modern password security standards and seeing some eye-opening vulnerability reports, I decided to bite the bullet and make the upgrade.

This article documents my entire journey - the research, the implementation challenges I faced, and the solutions I found. I hope it saves you some of the debugging time I spent staring at cryptic error messages at 2 AM.

Why This Upgrade Matters

Security Enhancement: Argon2 is the winner of the Password Hashing Competition and offers superior resistance to various attack vectors
Performance Optimization: Better tunable parameters for different deployment scenarios
Future-Proofing: Adopting industry-standard recommendations for password security
Architecture Improvement: Implementing clean separation between authentication logic and business logic

🔐 Part 1: Understanding Argon2 vs bcrypt

The Limitations of bcrypt

While bcrypt has served the industry well for over two decades, it has some inherent limitations:

// Traditional bcrypt approach (what we're moving away from)
use bcrypt::{hash, verify, DEFAULT_COST};

fn hash_password_bcrypt(password: &str) -> Result<String, bcrypt::BcryptError> {
    hash(password, DEFAULT_COST)
}

fn verify_password_bcrypt(password: &str, hash: &str) -> bool {
    verify(password, hash).unwrap_or(false)
}

bcrypt Limitations:

Memory Usage: Limited memory-hard properties
Parallel Resistance: Vulnerable to GPU-based attacks
Parameter Tuning: Limited customization options
Algorithm Age: Designed in 1999, before modern attack vectors

Argon2 Advantages

Argon2 addresses these limitations with three variants:

Argon2d: Maximum resistance against GPU attacks
Argon2i: Maximum resistance against side-channel attacks
Argon2id: Hybrid approach (recommended for most use cases)

🛠️ Part 2: Implementing the Argon2 Password Module

Here's where things got interesting. I initially tried to just swap out bcrypt calls with Argon2, but quickly realized I needed a more thoughtful approach. After some trial and error (and a few failed compilation attempts), here's the clean implementation I settled on:

// backend/src/core/password.rs
use crate::common::api::ServiceError;
use argon2::{
    Argon2,
    password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString, rand_core::OsRng},
};

/// Password utilities for secure hashing and verification.
pub struct PasswordUtils;

impl PasswordUtils {
    /// Hashes a plain-text password using Argon2.
    ///
    /// This function generates a random salt and uses Argon2 with default parameters
    /// to create a secure hash of the provided password.
    pub fn hash_password(password: &str) -> Result<String, ServiceError> {
        let salt = SaltString::generate(&mut OsRng);
        let argon2 = Argon2::default();
        let password_hash = argon2
            .hash_password(password.as_bytes(), &salt)
            .map_err(|_| ServiceError::PasswordHashingFailed)?
            .to_string();
        Ok(password_hash)
    }

    /// Verifies a password against a hash.
    ///
    /// This function parses the stored hash and verifies if the provided
    /// plain-text password matches the hash.
    pub fn verify_password(password: &str, hash: &str) -> bool {
        let parsed_hash = match PasswordHash::new(hash) {
            Ok(h) => h,
            Err(_) => return false,
        };
        Argon2::default().verify_password(password.as_bytes(), &parsed_hash).is_ok()
    }
}

What I Learned During Implementation

The biggest "aha!" moment came when I realized how much simpler the error handling could be with proper type design:

Salt Generation: I initially tried to manage salts manually (bad idea). Using SaltString::generate(&mut OsRng) was much cleaner and more secure.
Error Handling: This took me a while to get right. I wanted all password-related errors to flow through our existing ServiceError system, but Argon2's error types didn't map cleanly. The solution was creating a specific PasswordHashingFailed variant.
Default Parameters: I spent way too much time tweaking Argon2 parameters initially. Turns out the defaults are perfectly fine for most use cases - sometimes simpler is better.
Memory Safety: One of the reasons I love Rust - I don't have to worry about accidentally leaving password data in memory. The ownership system handles cleanup automatically.

Comprehensive Testing

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_password_hashing_and_verification() {
        let password = "test_password_123";

        // Test hashing
        let hash = PasswordUtils::hash_password(password).expect("Should hash password");
        assert!(!hash.is_empty());

        // Test verification with correct password
        assert!(PasswordUtils::verify_password(password, &hash));

        // Test verification with incorrect password
        assert!(!PasswordUtils::verify_password("wrong_password", &hash));
    }

    #[test]
    fn test_same_password_produces_different_hashes() {
        let password = "same_password";

        let hash1 = PasswordUtils::hash_password(password).expect("Should hash password");
        let hash2 = PasswordUtils::hash_password(password).expect("Should hash password");

        // Due to random salt, same password should produce different hashes
        assert_ne!(hash1, hash2);

        // But both should verify correctly
        assert!(PasswordUtils::verify_password(password, &hash1));
        assert!(PasswordUtils::verify_password(password, &hash2));
    }
}

🔒 Part 3: JWT Authentication Middleware Design

Now for the fun part - the JWT middleware. I'll be honest, this is where I made my biggest mistake initially. I tried to implement token verification directly in each route handler. After copy-pasting the same token extraction logic for the third time, I realized I needed a proper middleware approach.

Middleware Architecture

// backend/src/features/auth/middleware.rs
use crate::{
    common::api::{AppError, ServiceError},
    core::jwt,
};
use axum::{extract::Request, http::header, middleware::Next, response::Response};

pub async fn auth_middleware(request: Request, next: Next) -> Result<Response, AppError> {
    let (mut parts, body) = request.into_parts();

    // Extract Bearer token from Authorization header
    let token = parts
        .headers
        .get(header::AUTHORIZATION)
        .and_then(|value| value.to_str().ok())
        .and_then(|s| s.strip_prefix("Bearer "))
        .ok_or_else(|| AppError::from(ServiceError::InvalidCredentials))?;

    // Verify JWT token and extract claims
    let claims = jwt::verify_token(token).map_err(|_| ServiceError::InvalidToken)?;

    // Inject claims into request extensions for downstream handlers
    parts.extensions.insert(claims);

    let request = Request::from_parts(parts, body);

    Ok(next.run(request).await)
}

JWT Utility Functions

Pro tip: I initially put these functions directly in the middleware file, but quickly learned that separating JWT logic into its own module makes testing much easier:

// backend/src/core/jwt.rs (key excerpts)
use chrono::{Duration, Utc};
use jsonwebtoken::{Algorithm, DecodingKey, EncodingKey, Header, Validation, decode, encode};

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Claims {
    pub user_id: i64,
    pub username: String,
    pub exp: usize,
    pub iat: usize,
}

pub fn generate_token(user_id: i64, username: &str) -> Result<String, jsonwebtoken::errors::Error> {
    let now = Utc::now();
    let exp = (now + Duration::seconds(JWT_CONFIG.expiration)).timestamp() as usize;
    let iat = now.timestamp() as usize;

    let claims = Claims { user_id, username: username.to_string(), exp, iat };

    encode(&Header::default(), &claims, &EncodingKey::from_secret(JWT_CONFIG.secret.as_bytes()))
}

pub fn verify_token(token: &str) -> Result<Claims, jsonwebtoken::errors::Error> {
    let validation = Validation::new(Algorithm::HS256);
    let token_data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(JWT_CONFIG.secret.as_bytes()),
        &validation,
    )?;

    Ok(token_data.claims)
}

🔄 Part 4: Complete Authentication Flow Implementation

This is where everything comes together. I had to refactor the existing auth service to use our new password utilities, and honestly, it was more work than I initially expected. The tricky part was maintaining backward compatibility during the migration.

User Registration with Enhanced Security

// backend/src/features/auth/service.rs (key excerpts)
impl AuthService {
    pub async fn register(
        pool: &PgPool,
        request: RegisterRequest,
    ) -> Result<RegisterResponse, ServiceError> {
        tracing::info!("Attempting to register new user.");

        // Check for conflicts
        if UserRepository::find_by_username(pool, &request.username)
            .await
            .map_err(|e| {
                tracing::error!("DB error checking username: {:?}", e);
                ServiceError::DatabaseQueryFailed
            })?
            .is_some()
        {
            return Err(ServiceError::UsernameConflict);
        }

        // Hash password using new Argon2 implementation
        let password_hash = PasswordUtils::hash_password(&request.password)?;

        let new_user = UserRepository::create(
            pool,
            &request.username,
            &request.email,
            &password_hash,
            None, // real_name
            1,    // status
        )
        .await
        .map_err(|e| {
            tracing::error!("DB error creating user: {:?}", e);
            ServiceError::DatabaseQueryFailed
        })?;

        // Generate JWT token
        let token = jwt::generate_token(new_user.id, &new_user.username)
            .map_err(|e| {
                tracing::error!("Failed to generate token: {:?}", e);
                ServiceError::DatabaseQueryFailed
            })?;

        Ok(RegisterResponse {
            user: UserInfo { id: new_user.id, username: new_user.username },
            token,
        })
    }
}

Login Verification with Argon2

Here's a confession: I initially forgot to update the login verification logic and spent an embarrassing amount of time wondering why all login attempts were failing. Don't make my mistake - remember to update both registration AND login!

pub async fn verify_login(
    pool: &PgPool,
    username: &str,
    password: &str,
) -> Result<UserEntity, ServiceError> {
    let user = UserRepository::find_by_username(pool, username)
        .await
        .map_err(|_| ServiceError::DatabaseQueryFailed)?
        .ok_or(ServiceError::InvalidCredentials)?;

    if user.status == 0 {
        return Err(ServiceError::InvalidOperation("User is disabled".to_string()));
    }

    // Use new Argon2 verification
    if PasswordUtils::verify_password(password, &user.password_hash) {
        UserRepository::update_last_login(pool, user.id)
            .await
            .map_err(|_| ServiceError::DatabaseQueryFailed)?;
        Ok(user)
    } else {
        Err(ServiceError::InvalidCredentials)
    }
}

🔧 Part 5: Integration with Axum Framework

The Axum integration was surprisingly smooth once I figured out the right way to structure the route layers. The key insight was understanding that middleware order matters - a lot.

// backend/src/core/app.rs (key excerpts)
pub async fn create_server() -> Result<(), Box<dyn std::error::Error>> {
    let pool = create_default_pool().await?;

    // Define public and protected routes
    let public_api = Router::new().nest("/auth", public_auth_routes());

    let protected_api = Router::new()
        .nest("/auth", protected_auth_routes())
        .nest("/system", system_routes())
        .route_layer(middleware::from_fn(auth_middleware)); // Apply middleware here

    let app = Router::new()
        .route("/", get(root))
        .nest("/api", public_api.merge(protected_api))
        .layer(cors)
        .with_state(pool);

    // Server startup logic...
    Ok(())
}

Protected Route Example

One thing I love about this approach is how clean the route handlers become. The middleware does all the heavy lifting, and your handlers just focus on business logic:

// backend/src/features/auth/routes.rs
async fn get_user_info_handler(
    State(pool): State<PgPool>,
    Extension(claims): Extension<Claims>, // Injected by middleware
) -> AppResult<Json<ApiResponse<UserInfoResponse>>> {
    let response = AuthService::get_user_info(&pool, claims).await?;
    Ok(ApiResponse::success(response))
}

📊 Part 6: What I Learned About Security and Performance

Security Wins (and a few close calls)

I'll be honest - some of these I got right by accident, others I had to learn the hard way:

Salt Uniqueness: Argon2 handles this automatically, which is great because I initially tried to manage salts manually (rookie mistake).
Timing Attack Resistance: This was a happy accident - Argon2's verification is naturally constant-time, unlike some naive string comparison approaches I've seen.
Memory Security: Rust's ownership system saved me here. In other languages, I'd be paranoid about password strings lingering in memory.
Token Expiration: I learned to make this configurable after hardcoding a 1-hour expiration and getting locked out of my own app during testing.
Error Information: I initially returned detailed error messages (helpful for debugging, terrible for security). Now I return generic "invalid credentials" messages.

Performance Optimization

// Configuration for different environments
impl Default for DatabaseConfig {
    fn default() -> Self {
        Self {
            url: std::env::var("DATABASE_URL").expect("DATABASE_URL must be set"),
            max_connections: 10,
            min_connections: 1,
            connect_timeout: Duration::from_secs(30),
            idle_timeout: Duration::from_secs(600),
        }
    }
}

Migration Strategy (Lessons from the Trenches)

If you're migrating an existing system like I did, here's what actually worked (after a few false starts):

Dual Support: Temporarily support both bcrypt and Argon2
Gradual Migration: Hash new passwords with Argon2, verify old ones with bcrypt
User-Triggered Updates: Re-hash passwords during login
Monitoring: Track migration progress and performance impact

🎯 Wrapping Up: Was It Worth It?

Short answer: absolutely. Long answer: it was more work than I expected, but the peace of mind is worth it. Here's what this whole journey taught me:

Security upgrades don't have to be scary: With the right approach, you can upgrade critical systems without breaking everything.
Modern tools make things easier: Argon2 is actually simpler to use than bcrypt once you get the hang of it.
Architecture matters: Taking time to design clean interfaces (like our middleware) pays off in maintainability.
Rust is your friend: The type system caught so many potential bugs during this migration that would have been runtime errors in other languages.

What We've Achieved

✅ Enhanced Security: Migrated to Argon2 password hashing
✅ Robust Middleware: Implemented JWT authentication middleware
✅ Clean Architecture: Separated authentication concerns
✅ Comprehensive Testing: Added unit and integration tests
✅ Performance Optimization: Improved hash performance
✅ Future-Proofing: Adopted industry standards

What's Next?

I'm already thinking about the next improvements:

Multi-Factor Authentication: TOTP support is on my roadmap
Session Management: Refresh tokens would be nice for better UX
Rate Limiting: Need to add brute-force protection
Audit Logging: Better security event tracking

📎 All code from this article is available in the rustzen-admin repository. Key authentication modules:

core/password.rs - Argon2 password hashing implementation
core/jwt.rs - JWT utility functions
features/auth/service.rs - Authentication business logic
features/auth/middleware.rs - JWT authentication middleware

🔗 Complete Source Code: rustzen-admin on GitHub

🚀 Next in Series: Part 2 will dive into "Enterprise-Level Rust Backend Architecture: Elegant Implementation of Repository-Service-Routes Three-Tier Pattern" - where we'll explore how to build scalable, maintainable backend systems with proper separation of concerns.

Stay tuned for more insights from the rustzen-admin project!

Rust + React Admin Template with Axum, SQLx and Vite – Open Source

Bruce Dai — Sun, 22 Jun 2025 05:53:18 +0000

Introducing

Building admin panels often involves setting up the same foundational patterns: authentication, user management, CRUD operations, and API documentation. After working on several such projects, I decided to create rustzen-admin - a starter template that combines Rust backend with React frontend.

🎯 The Motivation

Every time I started a new project requiring an admin interface, I found myself:

Setting up basic authentication flows
Implementing standard CRUD operations
Configuring development environments
Writing API documentation
Organizing project structure

This repetitive setup work inspired me to build a template that provides a solid foundation while demonstrating modern development practices.

🛠️ Technology Stack

Backend: Rust + Axum

I chose Rust for the backend to leverage its performance and type safety:

Axum - Web framework with good ergonomics
SQLx - Compile-time checked SQL queries with PostgreSQL
Tokio - Async runtime for handling requests
Serde - JSON serialization/deserialization

Frontend: React + Modern Tooling

For the frontend, I used current React ecosystem tools:

React 19 - Latest React version
TypeScript - Type safety throughout the application
Vite - Fast build tool and dev server
TailwindCSS - Utility-first CSS framework
Ant Design Pro - UI component library
SWR - Data fetching with caching

🏗️ Project Structure

The template follows a clean, modular architecture:

rustzen-admin/
├── backend/         # Rust (Axum) API Service
├── frontend/        # React (Vite) Admin UI
├── docker/          # Docker configuration files
├── docs/            # Project documentation
├── justfile         # Command runner
└── README.md

Backend Architecture

Each feature module follows a consistent pattern:

features/
├── user/
│   ├── model.rs      // Data structures & validation
│   ├── repo.rs       // Database operations
│   ├── service.rs    // Business logic
│   ├── routes.rs     // HTTP handlers
│   └── mod.rs        // Module exports

This separation makes the code:

Testable - Each layer can be tested independently
Maintainable - Clear boundaries between responsibilities
Extensible - Easy to add new features

✨ Current Features

🔧 Development Setup

Docker-based development environment
Hot reload for both frontend and backend
Unified command runner with justfile
Environment configuration management

🗃️ Backend Foundation

Modular architecture with feature-based organization
PostgreSQL database integration via SQLx
CORS and logging middleware
Structured error handling
Mock data endpoints for rapid frontend development

🎨 Frontend Scaffold

React application with TypeScript
Component library integration (Ant Design Pro)
Routing system setup
State management foundation
Type-safe API integration with SWR for data fetching

🔄 Type Safety & Development Experience

Strict type alignment between frontend and backend
Mock data-driven development - frontend can develop independently with realistic data
Compile-time safety - TypeScript and Rust catch errors early
AI-friendly codebase - clean structure works well with modern development tools

📚 Documentation

API documentation and testing examples
Development setup guides
Architecture documentation

🚀 Getting Started

The setup process is straightforward:

# Clone the repository
git clone https://github.com/idaibin/rustzen-admin.git
cd rustzen-admin

# Set up environment variables
cp backend/.env.example backend/.env

# Install frontend dependencies (Node.js 24+ recommended)
cd frontend && pnpm install && cd ..

# Start development environment
just dev

The just dev command will:

Start PostgreSQL with Docker Compose
Start the Rust backend with hot reload
Start the React frontend with Vite
Open browser to http://localhost:5173

🎨 Code Examples

Type-Safe API Contracts

Frontend and backend share the same type definitions, ensuring consistency:

// Backend: Rust types
#[derive(Debug, Serialize, Deserialize)]
pub struct User {
    pub id: Uuid,
    pub username: String,
    pub email: String,
    pub created_at: DateTime<Utc>,
}

// Frontend: TypeScript types (auto-generated or manually synced)
interface User {
  id: string;
  username: string;
  email: string;
  created_at: string;
}

Error Handling Pattern

#[derive(Debug, thiserror::Error)]
pub enum UserError {
    #[error("User not found: {id}")]
    NotFound { id: Uuid },
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),
}

Repository Pattern

#[async_trait]
pub trait UserRepository {
    async fn find_by_id(&self, id: Uuid) -> Result<Option<User>, UserError>;
    async fn create(&self, user: CreateUser) -> Result<User, UserError>;
}

🔮 What's Next

This template provides a foundation that can be extended with:

JWT authentication implementation
Role-based access control
File upload functionality
Advanced UI components
Testing coverage
Database migration from mock data to real persistence

Want to contribute? We welcome issues and pull requests! The roadmap is community-driven.

🤝 Contributing

The project is MIT licensed and open to contributions. Areas where help would be appreciated:

Code review and architecture feedback
Documentation improvements
Testing strategies
Feature suggestions
Real-world usage feedback

🎉 Conclusion

rustzen-admin is a starting point for building admin systems with Rust and React. It's not a complete solution but rather a foundation that demonstrates clean architecture patterns, modern tooling integration, and type-safe full-stack development.

The current version includes mock data endpoints to enable rapid frontend development while the backend architecture is being finalized. This approach allows teams to work in parallel and iterate quickly.

If you're looking to start an admin project with Rust backend, this template might save you some initial setup time while providing a structure to build upon.

Links:

What do you think? Have you worked with similar tech stacks? I'd love to hear your experiences and suggestions!

Happy coding! 🦀⚛️

DEV Community: Bruce Dai

Frontend Simple Permission System Design and Implementation for Rustzen Admin

Overview

Core Architecture

1. Permission Data Structure

2. State Management - Zustand Store

Permission Verification Mechanism

1. Permission Code Verification

2. Route Permission Verification

Permission Component System

1. AuthGuard - Route Guard

2. AuthWrap - Component-Level Permission Control

3. AuthConfirm - Operation-Level Permission Control

Practical Application Examples

1. User Management Page Permission Control

2. Dynamic Menu Generation

Permission System Features

1. Fine-Grained Control

2. Intelligent Permission Matching

3. User Experience Optimization

4. Permission Code Naming Conventions

5. Component Usage Recommendations

🎯 Summary: Simple Permission Control Solution

Core Benefits

Technical Highlights

Applicable Scenarios

🧭 Final Thoughts

My Rust Backend Journey: A Practical Guide from 0 to 1

I. What is Rustzen? Why this naming?

II. Why adopt a three-layer architecture?

III. Why split data models into entity/dto/vo?

IV. Authentication & Authorization: JWT + Server-side Permission Cache

4.1 Middleware Architecture

Core Middleware Components

Middleware Implementation Example

Declarative Permission Usage Example

4.2 Permission Cache and Renewal Mechanism

Permission Cache Implementation Example

4.3 Permission Granularity and Declaration

4.4 Performance Optimization Strategies

V. Error Handling and Unified Response

Error Conversion Mechanism

VI. Response Format: Two Schemes Unified Processing

Scheme One: Simple Response Format

Scheme Two: Standard Pagination Format

VII. Database Migration Strategy: Zen-Style Numbering System

VIII. Module Dependency Relationship Management

Clear Module Boundaries

IX. AI-Assisted Programming: The More Zen the Structure, the Higher the Efficiency

X. Conclusion: Rust + Zen, Minimalism is Not Less, But Just Right

Architecture Advantages Summary

Future Improvement Directions

XI. Closing Message: A Growing Project, Welcome Resonance

Why I Choose Rust to Build a Full-Stack Admin System

🧠 How It Started: From Vite to Tauri

🤖 Learning by Doing (with AI)

🛠️ Why Not Java / Node / Bun?

🏗️ rustzen-admin: A Full-Stack Template in Rust + React

Tech Stack Overview:

✅ What's Done So Far

✨ Why I'll Continue Using Rust

📚 Resources

🧭 Final Thoughts

rustzen-admin: Complete Declarative Permission System Architecture for Axum Backends

I. Introduction: Why Design a Unified Permission System?

🔍 Pain Points of Traditional Permission Control

🎯 Our Solution

II. Design Goals and Principles

🎯 Core Goals of Permission System

✅ Design Principles

III. Permission System Architecture Overview

🔄 Complete Request Processing Flow

🏗️ Module Architecture Design

IV. Core Module Details

4.1 JWT Authentication Module

4.2 User Information Extractor CurrentUser

📋 CurrentUser vs Claims Semantic Differences

4.3 Intelligent Permission Caching Mechanism

V. Declarative Route Permission Binding Design

5.1 RouterExt Trait Design

4.2 User Information Extractor `CurrentUser`