OneAuth/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

VBase is a Go-based identity authentication and permission management framework built on the Vigo web framework (onion-model middleware architecture). It provides user management, scoped RBAC permissions, and OAuth2 authentication services.

• Language: Go 1.24+
• Framework: Vigo (onion-model middleware)
• ORM: GORM (MySQL, PostgreSQL, SQLite supported)
• Authentication: JWT + OAuth2
• Permissions: Scoped RBAC (Role-Based Access Control)
• Frontend: vhtml (embedded HTML-based UI at /vb/)

Common Commands

# Run development server (default port 4001)
make run

# Database operations
go run ./cli/main.go db migrate
go run ./cli/main.go db drop

# Run integration tests
go test -v ./tests/...

Architecture

Onion Model Request Flow

Request -> [Global Before Middlewares] -> [Router] -> [Handler] -> [Service] -> [Model] -> Database
                                              |
Response <- [Global After Middleware] <--------+

Directory Structure

├── api/              # REST API handlers and routing
│   ├── auth/         # Login, register, refresh token
│   ├── oauth/        # OAuth2 provider endpoints
│   ├── role/         # Role management
│   ├── user/         # User management
│   └── init.go       # Router aggregation
├── auth/             # Core Scoped RBAC permission system
│   ├── auth.go       # Permission checking implementation
│   └── design.md     # Permission system design doc
├── cfg/              # Configuration (DB, Redis, JWT settings)
├── models/           # GORM data models
│   ├── auth.go       # Role, Permission, UserRole models
│   ├── user.go       # User, Identity, Session models
│   └── init.go       # Model registration and migrations
├── libs/             # Utilities (cache, crypto, jwt, sms, email)
├── ui/               # Frontend admin interface (vhtml framework)
├── cli/              # Application entry point
└── tests/            # Go integration tests

Permission System (Scoped RBAC)

The system uses a scoped permission model where permissions are isolated by Scope (e.g., "vb" for VBase, "app1" for external apps).

Permission Format: resource:instance:sub-resource:sub-instance (Tree structure)

Levels:

• Level 1: Create (Odd layers)
• Level 2: Read (Even layers)
• Level 4: Write (Even layers)
• Level 7: Admin (Even layers, inherited downwards)

Key Interfaces:

• auth.Factory.New(scope): Get scoped auth instance.
• auth.PermRead(code), auth.PermWrite(code): Middleware checks.
• auth.Grant(ctx, userID, permID, level): Grant permission.

API Response Format

All responses are JSON formatted by common.JsonResponse middleware:

Success:

{"code": 200, "data": { ... }}

Error:

{ "code": 40001, "message": "Error description" }

Frontend (vhtml)

The admin UI is in ui/ using the vhtml framework:

• Access UI at /vb/ path when server is running
• Routes defined in ui/routes.js