iamjs - Your complete Access Control Library with End-to-end typesafety
MIT License
iamjs is a fully-featured and type-safe library that simplifies authorization in JavaScript and TypeScript applications. Designed for versatility, it supports both Node.js and browser environments, making it an ideal choice for a wide range of projects, from server-side applications to complex front-end systems.
iamjs offers multiple packages to suit your specific needs:
# For Express.js applications
npm install @iamjs/core @iamjs/express
# For Koa applications
npm install @iamjs/core @iamjs/koa
# For Next.js applications
npm install @iamjs/core @iamjs/next
# For React applications
npm install @iamjs/core @iamjs/react
# For framework-agnostic use
npm install @iamjs/core
For comprehensive documentation, including advanced features and API references, visit our official documentation site.
Define roles with specific permissions using the Role
class:
import { Role } from '@iamjs/core';
const userRole = new Role({
name: 'user',
description: 'Standard user role',
meta: {
createdAt: new Date(),
updatedAt: new Date()
},
config: {
posts: {
base: 'crudl',
custom: {
publish: true,
feature: false
}
},
comments: {
base: 'crud-'
}
}
});
This example creates a 'user' role with permissions for 'posts' and 'comments' resources. The 'base' property uses CRUD notation (create, read, update, delete, list), while 'custom' allows for additional specific actions.
Group roles into a schema for easier management:
import { Schema } from '@iamjs/core';
const schema = new Schema({
roles: {
user: userRole,
admin: adminRole // Assuming you've defined an adminRole
}
});
Integrate iamjs into an Express.js application:
import express from 'express';
import { ExpressRoleManager } from '@iamjs/express';
const app = express();
const roleManager = new ExpressRoleManager({
schema,
onError: (err, req, res, next) => {
res.status(403).json({ error: 'Access Denied', details: err.message });
},
onSuccess: (req, res, next) => {
next();
},
async onActivity(data) {
console.log('Authorization activity:', data);
// Implement your logging logic here
}
});
// authMiddleware checks if the user has permission to access the specified resources and actions
const authMiddleware = (resources, actions) => {
const role = 'user'; // Assuming the user is authenticated and has the 'user' role
return roleManager.check({
resources,
actions,
role,
strict: true
});
};
app.get('/posts',
authMiddleware('posts', ['read', 'list']),
(req, res) => {
res.json({ message: 'Posts retrieved successfully' });
}
);
app.listen(3000, () => console.log('Server running on http://localhost:3000'));
This setup checks if a 'user' role has permission to read and list posts before allowing access to the '/posts' route.
iamjs provides dedicated packages for popular frameworks:
@iamjs/express
@iamjs/koa
@iamjs/next
@iamjs/react
Each package offers framework-specific features while maintaining consistent core functionality.
For scenarios where roles need to be constructed dynamically (e.g., based on database data):
const roleManager = new ExpressRoleManager({
schema,
// ... other options
});
app.get('/dynamic-resource',
roleManager.check({
resources: 'dynamicResource',
actions: ['read'],
construct: true,
data: async (req) => {
// Fetch user permissions from database or JWT
const userPermissions = await getUserPermissions(req.user.id);
return userPermissions;
}
}),
(req, res) => {
res.json({ message: 'Access granted to dynamic resource' });
}
);
This approach allows for flexible, user-specific permissions that can be determined at runtime.
onActivity
handler to maintain an audit trail of authorization decisions.We welcome contributions to iamjs! Please read our contributing guide for details on our code of conduct and the process for submitting pull requests.
iamjs is released under the MIT License.