base-acl-api/README.md at master · gabrielmaialva33/base-acl-api

About | Technologies | Tools | Installation | License

🔖 About

Base ACL is a modular access control list API built with AdonisJS v6 that provides a robust foundation for authentication and role-based access control. The API follows clean architecture principles with clear separation of concerns and is designed to serve as a base for multiple projects.

🏗️ Architecture Overview

graph TB
    subgraph "Client Layer"
        WEB[Web Apps]
        MOB[Mobile Apps]
        API[External APIs]
    end

    subgraph "API Gateway - v1"
        ROUTES["/api/v1/*"]
        MW[Middleware Stack]
    end

    subgraph "Modules"
        AUTH[Auth Module<br/>JWT, Sessions]
        USER[User Module<br/>CRUD, Profile]
        ROLE[Role Module<br/>RBAC, Hierarchy]
        PERM[Permission Module<br/>Context-aware, Inheritance]
        FILE[File Module<br/>Upload, Storage]
        AUDIT[Audit Module<br/>Logging, Analytics]
        HEALTH[Health Module<br/>Status, Monitoring]
    end

    subgraph "Core Services"
        JWT[JWT Service]
        HASH[Hash Service]
        VALIDATOR[Validator Service]
        STORAGE[Storage Service]
    end

    subgraph "Data Layer"
        TS[(PostgreSQL<br/>Main Database)]
        REDIS[(Redis<br/>Cache & Sessions)]
        PGREST[PostgREST<br/>Auto-generated REST API]
    end

    WEB --> ROUTES
    MOB --> ROUTES
    API --> ROUTES

    ROUTES --> MW
    MW --> AUTH
    MW --> USER
    MW --> ROLE
    MW --> PERM
    MW --> FILE
    MW --> AUDIT
    MW --> HEALTH

    AUTH --> JWT
    AUTH --> HASH
    USER --> VALIDATOR
    FILE --> STORAGE
    PERM --> REDIS
    AUDIT --> TS

    USER --> TS
    ROLE --> TS
    PERM --> TS
    AUTH --> TS
    AUTH --> REDIS
    AUDIT --> TS

    TS --> PGREST

    style ROUTES fill:#4A90E2
    style TS fill:#336791
    style REDIS fill:#DC382D
    style PGREST fill:#008080

🔐 Authentication Flow

sequenceDiagram
    participant C as Client
    participant API as API Gateway
    participant AUTH as Auth Module
    participant JWT as JWT Service
    participant DB as PostgreSQL
    participant REDIS as Redis Cache

    C->>API: POST /api/v1/sessions/sign-in
    API->>AUTH: Validate credentials
    AUTH->>DB: Find user by email
    DB-->>AUTH: User data
    AUTH->>AUTH: Verify password hash
    AUTH->>JWT: Generate tokens
    JWT-->>AUTH: Access & Refresh tokens
    AUTH->>REDIS: Store session
    AUTH-->>C: Return tokens + user data

    Note over C,API: Subsequent requests

    C->>API: GET /api/v1/users (Bearer token)
    API->>AUTH: Validate JWT
    AUTH->>REDIS: Check session
    REDIS-->>AUTH: Session valid
    AUTH-->>API: User authenticated
    API-->>C: Return protected resource

📁 Module Structure

graph TD
    subgraph "Application Structure"
        APP[app/]
        MODULES[modules/]

        subgraph "User Module"
            USER_M[user/]
        end
        subgraph "Role Module"
            ROLE_M[role/]
        end
        subgraph "Permission Module"
            PERM_M[permission/]
        end
        subgraph "File Module"
            FILE_M[file/]
        end
        subgraph "Audit Module"
            AUDIT_M[audit/]
        end
        subgraph "Health Module"
            HEALTH_M[health/]
        end
        subgraph "Ownership Module"
            OWNER_M[ownership/]
        end
    end

    APP --> MODULES
    MODULES --> USER_M
    MODULES --> ROLE_M
    MODULES --> PERM_M
    MODULES --> FILE_M
    MODULES --> AUDIT_M
    MODULES --> HEALTH_M
    MODULES --> OWNER_M

🌟 Key Features

Core Features

🔐 JWT Authentication: Secure token-based authentication with refresh tokens
👥 Role-Based Access Control: Fine-grained permissions with ROOT, ADMIN, USER, EDITOR, and GUEST roles
📁 Modular Architecture: Clean separation of concerns with feature modules
🗄️ PostgreSQL: Robust and reliable database
🚀 RESTful API: Well-structured endpoints following REST principles
📤 File Uploads: Secure file handling with multiple storage drivers
🏥 Health Monitoring: Built-in health check endpoints
🔒 Security First: Password hashing, CORS, rate limiting ready
📝 Request Validation: DTOs with runtime validation
🌐 i18n Ready: Internationalization support built-in
🔗 PostgREST Integration: Auto-generated REST API for direct database access

Advanced ACL Features

🎯 Context-Aware Permissions: Support for own, any, team, and department contexts
🔄 Permission Inheritance: Automatic permission inheritance through role hierarchy
📋 Comprehensive Audit Trail: Track all permission checks and access attempts
⚡ Redis-Cached Permissions: High-performance permission checking with intelligent caching
🏢 Resource Ownership: Built-in ownership system supporting team and department contexts
🔍 Granular Permission Control: Resource + Action + Context based permission system

Database Schema

erDiagram
    USERS ||--o{ USER_ROLES : has
    ROLES ||--o{ USER_ROLES : has
    USERS ||--o{ USER_PERMISSIONS : has
    USERS ||--o{ FILES : uploads
    ROLES ||--o{ ROLE_PERMISSIONS : has
    PERMISSIONS ||--o{ ROLE_PERMISSIONS : has
    PERMISSIONS ||--o{ USER_PERMISSIONS : has
    USERS ||--o{ AUDIT_LOGS : generates

    USERS {
        bigint id PK
        string first_name
        string last_name
        string email UK
        string username UK
        string password
        string avatar_url
        boolean is_online
        timestamp deleted_at
        timestamp created_at
        timestamp updated_at
    }

    ROLES {
        bigint id PK
        string name
        string slug UK
        string description
        timestamp created_at
        timestamp updated_at
    }

    PERMISSIONS {
        bigint id PK
        string name UK
        string resource
        string action
        string context
        string description
        timestamp created_at
        timestamp updated_at
    }

    USER_ROLES {
        bigint id PK
        bigint user_id FK
        bigint role_id FK
        timestamp created_at
        timestamp updated_at
    }

    ROLE_PERMISSIONS {
        bigint id PK
        bigint role_id FK
        bigint permission_id FK
        timestamp created_at
        timestamp updated_at
    }

    USER_PERMISSIONS {
        bigint id PK
        bigint user_id FK
        bigint permission_id FK
        boolean granted
        timestamp expires_at
        timestamp created_at
        timestamp updated_at
    }

    AUDIT_LOGS {
        bigint id PK
        bigint user_id FK
        string resource
        string action
        string context
        bigint resource_id
        string result
        string reason
        string ip_address
        string user_agent
        json metadata
        timestamp created_at
    }

    FILES {
        bigint id PK
        bigint owner_id FK
        string client_name
        string file_name
        bigint file_size
        string file_type
        string file_category
        string url
        timestamp created_at
        timestamp updated_at
    }

💻 Technologies

Typescript
Node.js
AdonisJS
PostgreSQL
Redis - In-memory data store
PostgREST - Auto-generated REST API
Docker

🔧 Tools

WebStorm
Insomnia
DataGrip

📦 Installation

✔️ Prerequisites

The following software must be installed:

Node.js
Git
NPM or Yarn
PostgreSQL or Docker

⬇️ Cloning the repository

  $ git clone https://github.com/gabrielmaialva33/base-acl-api.git

▶️ Running the application

📦 API

  $ cd base-acl-api
  # Dependencies install.
  $ yarn # or npm install
  # Config environment system
  $ cp .env.example .env
  # Data base creation.
  $ node ace migration:run # or docker-compose up --build
  # API start
  $ node ace serve --hmr # or pnpm dev

🔀 API Routes

The API is versioned and all endpoints are prefixed with /api/v1/. Below is the complete route structure:

🛣️ Route Organization

graph LR
    subgraph "Public Routes"
        HOME[GET /]
        HEALTH[GET /api/v1/health]
        SIGNIN[POST /api/v1/sessions/sign-in]
        SIGNUP[POST /api/v1/sessions/sign-up]
    end

    subgraph "Protected Routes"
        subgraph "User Routes"
            USER_LIST[GET /api/v1/users]
            USER_GET[GET /api/v1/users/:id]
            USER_CREATE[POST /api/v1/users]
            USER_UPDATE[PUT /api/v1/users/:id]
            USER_DELETE[DELETE /api/v1/users/:id]
        end

        subgraph "Admin Routes"
            ROLE_LIST[GET /api/v1/admin/roles]
            ROLE_ATTACH[PUT /api/v1/admin/roles/attach]
        end

        subgraph "File Routes"
            FILE_UPLOAD[POST /api/v1/files/upload]
        end
    end

    style HOME fill:#90EE90
    style HEALTH fill:#90EE90
    style SIGNIN fill:#90EE90
    style SIGNUP fill:#90EE90
    style ROLE_LIST fill:#FFB6C1
    style ROLE_ATTACH fill:#FFB6C1

📋 Route Details

Method	Endpoint	Description	Auth Required	Permission/Role
GET	`/`	API information	❌	-
GET	`/api/v1/health`	Health check	❌	-
POST	`/api/v1/sessions/sign-in`	User login	❌	-
POST	`/api/v1/sessions/sign-up`	User registration	❌	-
GET	`/api/v1/verify-email`	Verify user email	❌	-
POST	`/api/v1/resend-verification-email`	Resend verification email	✅	-
GET	`/api/v1/me`	Get current user profile	✅	-
GET	`/api/v1/me/permissions`	Get current user permissions	✅	-
GET	`/api/v1/me/roles`	Get current user roles	✅	-
GET	`/api/v1/users`	List users (paginated)	✅	users.list
GET	`/api/v1/users/:id`	Get user by ID	✅	users.read
POST	`/api/v1/users`	Create user	✅	users.create
PUT	`/api/v1/users/:id`	Update user	✅	users.update
DELETE	`/api/v1/users/:id`	Delete user	✅	users.delete
GET	`/api/v1/admin/roles`	List roles	✅	ROOT, ADMIN
PUT	`/api/v1/admin/roles/attach`	Attach role to user	✅	ROOT, ADMIN
GET	`/api/v1/admin/permissions`	List permissions	✅	permissions.list
POST	`/api/v1/admin/permissions`	Create permission	✅	permissions.create
PUT	`/api/v1/admin/roles/permissions/sync`	Sync role permissions	✅	permissions.update
PUT	`/api/v1/admin/roles/permissions/attach`	Attach permissions to role	✅	permissions.update
PUT	`/api/v1/admin/roles/permissions/detach`	Detach permissions from role	✅	permissions.update
PUT	`/api/v1/admin/users/permissions/sync`	Sync user permissions	✅	permissions.update
GET	`/api/v1/admin/users/:id/permissions`	Get user's direct permissions	✅	permissions.list
POST	`/api/v1/admin/users/:id/permissions/check`	Check user permissions	✅	permissions.list
POST	`/api/v1/files/upload`	Upload file	✅	files.create

🔄 Request/Response Flow

sequenceDiagram
    participant Client
    participant Router
    participant Middleware
    participant Controller
    participant Service
    participant Repository
    participant Database

    Client->>Router: HTTP Request
    Router->>Middleware: Route Match

    alt Protected Route
        Middleware->>Middleware: Auth Check
        Middleware->>Middleware: ACL Check
    end

    Middleware->>Controller: Request Validated
    Controller->>Service: Business Logic
    Service->>Repository: Data Access
    Repository->>Database: Query
    Database-->>Repository: Result
    Repository-->>Service: Entity/DTO
    Service-->>Controller: Response Data
    Controller-->>Client: HTTP Response

🔐 Permission System

The advanced permission system supports context-aware access control:

graph TD
    subgraph "Permission Structure"
        P[Permission]
        P --> R[Resource]
        P --> A[Action]
        P --> C[Context]

        R --> |examples| R1[users]
        R --> |examples| R2[files]
        R --> |examples| R3[permissions]

        A --> |examples| A1[create]
        A --> |examples| A2[read]
        A --> |examples| A3[update]
        A --> |examples| A4[delete]
        A --> |examples| A5[list]

        C --> |examples| C1[own - Own resources only]
        C --> |examples| C2[any - Any resource]
        C --> |examples| C3[team - Team resources]
        C --> |examples| C4[department - Department resources]
    end

Role Hierarchy & Inheritance

ROOT
├── ADMIN (inherits all ROOT permissions)
│   ├── USER (inherits basic ADMIN permissions)
│   │   └── GUEST (inherits limited USER permissions)
│   └── EDITOR (inherits content ADMIN permissions)
       └── USER (inherits from EDITOR)

Context Examples

users.update.own - Can only update own profile
users.update.any - Can update any user
files.delete.team - Can delete files from team members
reports.read.department - Can read reports from own department

📥 Insomnia Collection

Get the complete API collection for Insomnia: Download

📝 License

This project is under the MIT license. MIT ❤️

Liked? Leave a little star to help the project ⭐

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🔖 About

🏗️ Architecture Overview

🔐 Authentication Flow

📁 Module Structure

🌟 Key Features

Core Features

Advanced ACL Features

Database Schema

💻 Technologies

🔧 Tools

📦 Installation

✔️ Prerequisites

⬇️ Cloning the repository

▶️ Running the application

🔀 API Routes

🛣️ Route Organization

📋 Route Details

🔄 Request/Response Flow

🔐 Permission System

Role Hierarchy & Inheritance

Context Examples

📥 Insomnia Collection

📝 License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🔖 About

🏗️ Architecture Overview

🔐 Authentication Flow

📁 Module Structure

🌟 Key Features

Core Features

Advanced ACL Features

Database Schema

💻 Technologies

🔧 Tools

📦 Installation

✔️ Prerequisites

⬇️ Cloning the repository

▶️ Running the application

🔀 API Routes

🛣️ Route Organization

📋 Route Details

🔄 Request/Response Flow

🔐 Permission System

Role Hierarchy & Inheritance

Context Examples

📥 Insomnia Collection

📝 License