express-permission

OracleDB Role and Permission Service for Express.js, inspired by Spatie Laravel Permission. Allows flexible and scoped role-permission management directly in your service layer.

• ✅ Framework-agnostic – suitable for Express or any Node.js app
• ✅ OracleDB native – no abstraction, no ORM
• ✅ Scoped permissions – supports multi-tenancy (e.g. organization, team)
• ✅ Simple API – check with hasPermission() or hasRole()

📦 Installation

npm install @avisenaalwi/express-permission oracledb

⚙️ Configuration

Create a permission.config.ts in your project root:

import { PermissionConfig } from '@avisenaalwi/express-permission';

const config: PermissionConfig = {
  userTable: 'USERS',
  userPrimaryKey: 'ID',

  roleTable: 'ROLES',
  rolePrimaryKey: 'ID',
  roleNameColumn: 'NAME',

  permissionTable: 'PERMISSIONS',
  permissionPrimaryKey: 'ID',
  permissionNameColumn: 'NAME',

  userRolesTable: 'USER_ROLE',
  userRolesUserId: 'USER_ID',
  userRolesRoleId: 'ROLE_ID',
  userRolesScopeParams: [
    { name: 'orgId', column: 'ORG_ID' }
  ],

  rolePermissionsTable: 'ROLE_PERMISSION',
  rolePermissionsRoleId: 'ROLE_ID',
  rolePermissionsPermissionId: 'PERMISSION_ID',
  rolePermissionsScopeParams: []
};

export default config;

🛠 Usage

1. Setup Oracle pool

import oracledb from 'oracledb';
import { PermissionService } from '@avisenaalwi/express-permission';

const pool = await oracledb.createPool({
  user: 'your_user',
  password: 'your_password',
  connectString: 'your_connect_string'
});

const permissionService = new PermissionService(pool);

2. Check Permission or Role

const userId = 42;

const hasEdit = await permissionService.hasPermission(userId, 'edit-post');
if (!hasEdit) {
  return res.status(403).json({ message: 'Forbidden' });
}

const isAdmin = await permissionService.hasRole(userId, 'admin');

With scope:

await permissionService.hasPermission(userId, 'edit-post', { orgId: 1001 });

3. Get all permissions or roles

const permissions = await permissionService.getPermissions(userId);
const roles = await permissionService.getRoles(userId);

✅ Table Requirements

You must provide:

• users table with id
• roles and permissions tables
• user_roles relation table
• role_permissions relation table

The names and columns can be fully customized via permission.config.ts.

📌 Optional Features

• Multi-tenancy: Use scoped permission by adding columns like ORG_ID and declaring them in config.
• You can extend PermissionService with caching (e.g. Redis) or override methods as needed.

🧪 Testing

// Example test
expect(await permissionService.hasPermission(1, 'read-dashboard')).toBe(true);

📤 Planned Features

• CLI for migration and schema check
• Middleware helpers for Express
• Caching support (Redis)
• Role/Permission sync like Spatie

📄 License

MIT © 2025 Avisena Alwi