;
}
```
## Basic Usage
### Update User
```svelte
Login
Logout
```
### Check Permissions
```svelte
{#if $canWrite}
Create Post
{/if}
{#if $isAdmin}
Admin Panel
{/if}
```
## Reactive Stores
### can(permission)
```svelte
{#if $canWrite}
Edit
{/if}
{#if $canPublish}
Publish
{/if}
{#if $canDelete}
Delete
{/if}
```
### hasRole(role)
```svelte
Home
{#if $isEditor}
Posts
{/if}
{#if $isAdmin}
Admin
{/if}
```
### authorize(permission)
```svelte
{#if !$result.allowed}
Access denied: {$result.reason}
{:else}
Delete Post
{/if}
```
### canAll(permissions)
```svelte
{#if $hasFullAccess}
Full Access Mode
{/if}
```
### canAny(permissions)
```svelte
{#if $canAccessPosts}
View Posts
{/if}
```
## Svelte Actions
### use:can
```svelte
Create Post
Create Post
```
### use:role
```svelte
```
### use:cannot
```svelte
Upgrade to Premium for more features!
Upgrade Now
```
## Component Examples
### Navigation Menu
```svelte
Home
{#if $canManagePosts}
Posts
{/if}
{#if $canManageUsers}
Users
{/if}
{#if $isAdmin}
Admin
{/if}
```
### Post Actions
```svelte
{#if $canEdit}
Edit
{/if}
{#if $canPublish}
Publish
{/if}
{#if $canDelete}
Delete
{/if}
```
### User Login/Logout
```svelte
{#if isLoggedIn}
Logged in as: {$rbacStore.user?.id}
Logout
{:else}
Login as Admin
Login as Editor
Login as Viewer
{/if}
```
### Form with Conditional Fields
```svelte
```
### Using Actions
```svelte
Create Post
Admin Controls
This section is only visible to administrators
Upgrade to Premium for more features!
Upgrade Now
```
## SvelteKit Integration
### Layout with RBAC
```svelte
Home
{#if $isAdmin}
Admin
{/if}
Admin Dashboard
{/if}
```
### Server Load Function
```typescript
// routes/admin/+page.server.ts
import type { PageServerLoad } from './$types';
export const load: PageServerLoad = async ({ locals }) => {
const user = locals.user;
if (!user || !user.roles.includes('admin')) {
throw redirect(303, '/unauthorized');
}
return {
user
};
};
```
## TypeScript Support
```typescript
import type { RBACUser } from '@fire-shield/svelte';
interface User extends RBACUser {
email: string;
name: string;
}
const user: User = {
id: 'user-1',
roles: ['editor'],
email: 'user@example.com',
name: 'John Doe',
};
rbacStore.user.set(user);
```
## Best Practices
### 1. Use Derived Stores
```typescript
// Create derived stores for commonly used checks
const canEdit = rbacStore.can('post:edit');
const canDelete = rbacStore.can('post:delete');
const isAdmin = rbacStore.hasRole('admin');
```
### 2. Centralize Permission Logic
```typescript
// lib/permissions.ts
import { rbacStore } from './stores/rbac';
import { derived } from 'svelte/store';
export const permissions = {
canManageUsers: derived(rbacStore.user, ($user) =>
rbacStore.rbac.hasPermission($user, 'user:manage')
),
canEditPost: (post: Post) =>
derived(rbacStore.user, ($user) => {
if (!$user) return false;
return (
rbacStore.rbac.hasPermission($user, 'post:edit:any') ||
(post.authorId === $user.id &&
rbacStore.rbac.hasPermission($user, 'post:edit:own'))
);
}),
};
```
### 3. Use Actions for Declarative UI
```svelte
Create Post
```
## Next Steps
### SvelteKit Integration
> Source: https://fire-shield.dev/frameworks/sveltekit
# SvelteKit Integration
## Features
## Installation
```bash
npm install @fire-shield/sveltekit@3.1.1 @fire-shield/core@3.1.1
```
## Quick Start
### 1. Initialize RBAC
```typescript
// src/lib/rbac.ts
import { RBAC } from '@fire-shield/core';
export const rbac = new RBAC();
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);
rbac.createRole('viewer', ['post:read']);
```
### 2. Setup Hooks
```typescript
// src/hooks.server.ts
import { createRBACHandle } from '@fire-shield/sveltekit';
import { rbac } from '$lib/rbac';
export const handle = createRBACHandle(rbac, {
getUser: async (event) => {
// Get user from session/cookie
const session = await event.locals.getSession();
return session?.user;
}
});
```
### 3. Use in Pages
```svelte
{#if canManageUsers}
Create User
{/if}
```
## API
### createRBACHandle(rbac, options)
```typescript
interface RBACHandleOptions {
getUser?: (event: RequestEvent) => Promise | RBACUser | undefined;
onUnauthorized?: (event: RequestEvent, result: AuthorizationResult) => Response;
}
```
```typescript
// src/hooks.server.ts
import { createRBACHandle } from '@fire-shield/sveltekit';
import { redirect } from '@sveltejs/kit';
export const handle = createRBACHandle(rbac, {
getUser: async (event) => {
const sessionId = event.cookies.get('session');
if (!sessionId) return undefined;
return await getUserFromSession(sessionId);
},
onUnauthorized: (event, result) => {
throw redirect(303, '/login');
}
});
```
### requirePermission(permission)
```typescript
// src/routes/admin/+page.server.ts
import { requirePermission } from '@fire-shield/sveltekit';
export const load = requirePermission('admin:access', async (event) => {
// This only runs if user has 'admin:access' permission
const users = await getUsers();
return { users };
});
```
### requireRole(role)
```typescript
// src/routes/admin/+page.server.ts
import { requireRole } from '@fire-shield/sveltekit';
export const load = requireRole('admin', async (event) => {
// This only runs if user has 'admin' role
const settings = await getAdminSettings();
return { settings };
});
```
## Server-Side Protection
### Protecting Load Functions
```typescript
// src/routes/posts/+page.server.ts
import { requirePermission } from '@fire-shield/sveltekit';
export const load = requirePermission('post:read', async ({ locals }) => {
const posts = await db.post.findMany();
return { posts };
});
```
### Protecting Actions
```typescript
// src/routes/posts/+page.server.ts
import { requirePermission } from '@fire-shield/sveltekit';
import { fail } from '@sveltejs/kit';
export const actions = {
create: requirePermission('post:write', async ({ request, locals }) => {
const data = await request.formData();
const title = data.get('title');
await db.post.create({
data: { title, authorId: locals.user.id }
});
return { success: true };
}),
delete: requirePermission('post:delete', async ({ request }) => {
const data = await request.formData();
const postId = data.get('postId');
await db.post.delete({ where: { id: postId } });
return { success: true };
})
};
```
### Custom Authorization Logic
```typescript
// src/routes/posts/[id]/+page.server.ts
import type { PageServerLoad } from './$types';
export const load: PageServerLoad = async ({ params, locals }) => {
const post = await db.post.findUnique({ where: { id: params.id } });
// Custom authorization: Check if user owns the post or is admin
const canEdit =
locals.rbac.hasPermission(locals.user, 'post:edit') &&
(post.authorId === locals.user.id || locals.rbac.hasRole(locals.user, 'admin'));
return {
post,
canEdit
};
};
```
## Client-Side Usage
### In Svelte Components
```svelte
{#if rbac.hasPermission(user, 'post:write')}
Create Post
{/if}
{#if rbac.hasPermission(user, 'post:delete')}
Delete All Posts
{/if}
```
### Reactive Permission Checks
```svelte
{#if canWrite}
You don't have permission to create posts.
{/if}
```
```typescript
// src/routes/posts/create/+page.server.ts
import { requirePermission } from '@fire-shield/sveltekit';
import { redirect } from '@sveltejs/kit';
export const actions = {
default: requirePermission('post:write', async ({ request, locals }) => {
const data = await request.formData();
await db.post.create({
data: {
title: data.get('title'),
content: data.get('content'),
authorId: locals.user.id
}
});
throw redirect(303, '/posts');
})
};
```
## API Routes Protection
```typescript
// src/routes/api/users/+server.ts
import { json } from '@sveltejs/kit';
import { requirePermission } from '@fire-shield/sveltekit';
import type { RequestHandler } from './$types';
export const GET: RequestHandler = requirePermission('user:read', async () => {
const users = await db.user.findMany();
return json(users);
});
export const POST: RequestHandler = requirePermission('user:write', async ({ request }) => {
const data = await request.json();
const user = await db.user.create({ data });
return json(user, { status: 201 });
});
export const DELETE: RequestHandler = requirePermission('user:delete', async ({ request }) => {
const { id } = await request.json();
await db.user.delete({ where: { id } });
return json({ success: true });
});
```
## Error Handling
```typescript
// src/hooks.server.ts
import { createRBACHandle } from '@fire-shield/sveltekit';
import { error } from '@sveltejs/kit';
export const handle = createRBACHandle(rbac, {
getUser: async (event) => {
return await getUserFromSession(event);
},
onUnauthorized: (event, result) => {
throw error(403, {
message: 'Access Denied',
reason: result.reason
});
}
});
```
## Best Practices
## Advanced Example
```typescript
// src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import { createRBACHandle } from '@fire-shield/sveltekit';
import { redirect } from '@sveltejs/kit';
const authHandle = async ({ event, resolve }) => {
const sessionId = event.cookies.get('session');
if (sessionId) {
const user = await getUserFromSession(sessionId);
event.locals.user = user;
}
return resolve(event);
};
const rbacHandle = createRBACHandle(rbac, {
getUser: (event) => event.locals.user,
onUnauthorized: () => {
throw redirect(303, '/login');
}
});
export const handle = sequence(authHandle, rbacHandle);
```
## Next Steps
============================================================
## Frameworks — Backend
============================================================
### Express Integration
> Source: https://fire-shield.dev/frameworks/express
# Express Integration
## Installation
```bash
npm install @fire-shield/express@3.1.1 @fire-shield/core@3.1.1 express
```
## Setup
### Basic Setup
```typescript
import express from 'express'
import { RBAC } from '@fire-shield/core'
import { ExpressRBACAdapter } from '@fire-shield/express'
const app = express()
const rbac = new RBAC()
// Define roles
rbac.createRole('admin', ['posts:*', 'users:*'])
rbac.createRole('editor', ['posts:read', 'posts:write'])
rbac.createRole('viewer', ['posts:read'])
// Create RBAC adapter
const rbacMiddleware = new ExpressRBACAdapter(rbac, {
getUser: (req) => req.user // Get user from request
})
```
## Middleware
### requirePermission
```typescript
import { requirePermission } from '@fire-shield/express'
// Require single permission
app.post('/posts',
requirePermission('posts:write', { rbac }),
(req, res) => {
res.json({ message: 'Post created' })
}
)
app.delete('/posts/:id',
requirePermission('posts:delete', { rbac }),
(req, res) => {
res.json({ message: 'Post deleted' })
}
)
```
### adapter.permission
```typescript
app.post('/posts',
rbacMiddleware.permission('posts:write'),
(req, res) => {
res.json({ message: 'Post created' })
}
)
```
### adapter.any / adapter.all
```typescript
// Require at least one permission
app.get('/admin',
rbacMiddleware.any('admin:access', 'moderator:access'),
(req, res) => {
res.json({ message: 'Admin panel' })
}
)
// Require all permissions
app.delete('/posts/:id',
rbacMiddleware.all('posts:delete', 'posts:own'),
(req, res) => {
res.json({ message: 'Post deleted' })
}
)
```
### requireRole
```typescript
import { requireRole } from '@fire-shield/express'
// Require single role
app.get('/admin/users',
requireRole('admin', { rbac }),
(req, res) => {
res.json({ users: [] })
}
)
```
### adapter.role
```typescript
app.get('/admin/users',
rbacMiddleware.role('admin'),
(req, res) => {
res.json({ users: [] })
}
)
```
### requireResourceAction
```typescript
import { requireResourceAction } from '@fire-shield/express'
app.delete('/users/:id',
requireResourceAction('users', 'delete', { rbac }),
(req, res) => {
res.json({ message: 'User deleted' })
}
)
```
### denyPermission
```typescript
import { denyPermission } from '@fire-shield/express'
// Deny a permission for the user making this request
app.post('/restrict',
denyPermission('posts:delete', { rbac }),
(req, res) => {
res.json({ message: 'posts:delete has been denied for your account' })
}
)
```
### allowPermission
```typescript
import { allowPermission } from '@fire-shield/express'
// Remove a previously denied permission
app.post('/restore',
allowPermission('posts:delete', { rbac }),
(req, res) => {
res.json({ message: 'posts:delete has been restored' })
}
)
```
### requireNotDenied
```typescript
import { requireNotDenied } from '@fire-shield/express'
// Block if permission is in the deny list (even if role grants it)
app.delete('/posts/:id',
requireNotDenied('posts:delete', { rbac }),
rbacMiddleware.permission('posts:delete'),
(req, res) => {
res.json({ message: 'Post deleted' })
}
)
```
## Custom Error Handling
### Default Behavior
```typescript
// Default response for denied access
{
error: 'Forbidden',
message: 'Insufficient permissions'
}
```
### Custom Error Handler
```typescript
const rbacMiddleware = new ExpressRBACAdapter(rbac, {
getUser: (req) => req.user,
onUnauthorized: (result, req, res, next) => {
res.status(403).json({
error: 'Access Denied',
message: result.reason,
requiredPermission: result.reason
})
}
})
```
### Error Middleware
```typescript
app.use((err, req, res, next) => {
if (err.name === 'RBACError') {
return res.status(403).json({
error: 'RBAC Error',
message: err.message,
permission: err.permission
})
}
next(err)
})
```
## Authentication Integration
### With Passport.js
```typescript
import passport from 'passport'
app.use(passport.initialize())
app.post('/posts',
passport.authenticate('jwt', { session: false }),
rbacMiddleware.permission('posts:write'),
(req, res) => {
// req.user is set by passport
res.json({ message: 'Post created' })
}
)
```
### With Express Session
```typescript
import session from 'express-session'
app.use(session({
secret: 'your-secret',
resave: false,
saveUninitialized: true
}))
// Attach user to request from session
app.use((req, res, next) => {
if (req.session.userId) {
req.user = getUserById(req.session.userId)
}
next()
})
// Use RBAC middleware
app.post('/posts',
rbacMiddleware.permission('posts:write'),
(req, res) => {
res.json({ message: 'Post created' })
}
)
```
### With JWT
```typescript
import jwt from 'jsonwebtoken'
// JWT middleware
app.use((req, res, next) => {
const token = req.headers.authorization?.replace('Bearer ', '')
if (token) {
try {
req.user = jwt.verify(token, 'secret')
} catch (err) {
// Invalid token
}
}
next()
})
// RBAC middleware
app.delete('/posts/:id',
rbacMiddleware.permission('posts:delete'),
(req, res) => {
res.json({ message: 'Post deleted' })
}
)
```
## Programmatic Permission Checks
```typescript
app.get('/posts/:id', (req, res) => {
const post = getPost(req.params.id)
// req.authorization is set by the RBAC middleware after a successful check
const authorized = req.authorization?.allowed
res.json(post)
})
```
## Dynamic Permissions
```typescript
import { requirePermission } from '@fire-shield/express'
app.delete('/posts/:id',
requirePermission('posts:delete', { rbac }),
async (req, res) => {
const post = await getPost(req.params.id)
// Check if user owns the post
const isOwner = post.authorId === req.user.id
if (!isOwner) {
return res.status(403).json({ error: 'Forbidden' })
}
await deletePost(req.params.id)
res.json({ message: 'Post deleted' })
}
)
```
## Route Organization
### Grouped Routes
```typescript
const adminRouter = express.Router()
// All admin routes require admin role
adminRouter.use(rbacMiddleware.role('admin'))
adminRouter.get('/users', (req, res) => {
res.json({ users: [] })
})
adminRouter.post('/users', (req, res) => {
res.json({ message: 'User created' })
})
app.use('/admin', adminRouter)
```
### Nested Permissions
```typescript
const postsRouter = express.Router()
// All routes require read permission
postsRouter.use(rbacMiddleware.permission('posts:read'))
postsRouter.get('/', (req, res) => {
res.json({ posts: [] })
})
// Additional permission for write
postsRouter.post('/',
rbacMiddleware.permission('posts:write'),
(req, res) => {
res.json({ message: 'Post created' })
}
)
// Additional permission for delete
postsRouter.delete('/:id',
rbacMiddleware.permission('posts:delete'),
(req, res) => {
res.json({ message: 'Post deleted' })
}
)
app.use('/posts', postsRouter)
```
## TypeScript Support
```typescript
import { Request, Response, NextFunction } from 'express'
import { RBACUser, AuthorizationResult } from '@fire-shield/core'
// Express Request is already extended by @fire-shield/express:
// req.user?: RBACUser
// req.authorization?: AuthorizationResult
// Type-safe route handler
app.get('/posts', (req: Request, res: Response) => {
if (req.authorization?.allowed) {
// Access granted
}
})
```
## Best Practices
### 1. Protect All Sensitive Routes
```typescript
// ✅ Good: Protected routes
app.post('/posts',
rbacMiddleware.permission('posts:write'),
createPost
)
app.delete('/posts/:id',
rbacMiddleware.permission('posts:delete'),
deletePost
)
// ❌ Avoid: Unprotected sensitive routes
app.delete('/posts/:id', deletePost)
```
### 2. Use Router-Level Middleware
```typescript
// ✅ Good: Protect entire router
const adminRouter = express.Router()
adminRouter.use(rbacMiddleware.role('admin'))
adminRouter.get('/users', getUsers)
adminRouter.post('/users', createUser)
// ❌ Avoid: Repeat on every route
app.get('/admin/users',
rbacMiddleware.role('admin'),
getUsers
)
app.post('/admin/users',
rbacMiddleware.role('admin'),
createUser
)
```
### 3. Handle Errors Gracefully
```typescript
// ✅ Good: Custom error handling
const rbacMiddleware = new ExpressRBACAdapter(rbac, {
getUser: (req) => req.user,
onUnauthorized: (result, req, res, next) => {
console.warn(`Access denied to ${req.path}`, {
user: req.user?.id,
reason: result.reason
})
res.status(403).json({
error: 'Forbidden',
message: 'Insufficient permissions'
})
}
})
```
### 4. Document Permission Requirements
```typescript
/**
* Create a new post
* @route POST /posts
* @permission posts:write
* @returns {Post} Created post
*/
app.post('/posts',
rbacMiddleware.permission('posts:write'),
createPost
)
```
## Complete Example
```typescript
import express from 'express'
import { RBAC } from '@fire-shield/core'
import { ExpressRBACAdapter } from '@fire-shield/express'
const app = express()
const rbac = new RBAC()
// Setup roles
rbac.createRole('admin', ['*'])
rbac.createRole('editor', ['posts:*', 'comments:*'])
rbac.createRole('viewer', ['posts:read', 'comments:read'])
// RBAC adapter
const rbacMiddleware = new ExpressRBACAdapter(rbac, {
getUser: (req) => req.user,
onUnauthorized: (result, req, res, next) => {
res.status(403).json({
error: 'Forbidden',
message: result.reason || 'Insufficient permissions'
})
}
})
app.use(express.json())
// Public routes
app.get('/health', (req, res) => {
res.json({ status: 'ok' })
})
// Protected routes
app.get('/posts',
rbacMiddleware.permission('posts:read'),
(req, res) => {
res.json({ posts: [] })
}
)
app.post('/posts',
rbacMiddleware.permission('posts:write'),
(req, res) => {
res.json({ message: 'Post created' })
}
)
app.delete('/posts/:id',
rbacMiddleware.permission('posts:delete'),
(req, res) => {
res.json({ message: 'Post deleted' })
}
)
// Admin routes
const adminRouter = express.Router()
adminRouter.use(rbacMiddleware.role('admin'))
adminRouter.get('/users', (req, res) => {
res.json({ users: [] })
})
adminRouter.post('/users', (req, res) => {
res.json({ message: 'User created' })
})
app.use('/admin', adminRouter)
app.listen(3000, () => {
console.log('Server running on http://localhost:3000')
})
```
## Next Steps
### Fastify Integration
> Source: https://fire-shield.dev/frameworks/fastify
# Fastify Integration
## Installation
```bash
npm install @fire-shield/fastify@3.1.1 @fire-shield/core@3.1.1 fastify
```
## Setup
### Basic Setup
```typescript
import Fastify from 'fastify'
import { RBAC } from '@fire-shield/core'
import { FastifyRBACAdapter, fastifyRBACPlugin } from '@fire-shield/fastify'
const fastify = Fastify()
const rbac = new RBAC()
// Define roles
rbac.createRole('admin', ['posts:*', 'users:*'])
rbac.createRole('editor', ['posts:read', 'posts:write'])
rbac.createRole('viewer', ['posts:read'])
// Create RBAC adapter
const rbacHooks = new FastifyRBACAdapter(rbac, {
getUser: (request) => request.user
})
// Optionally register as a Fastify plugin (decorates fastify.rbac and fastify.authorize)
fastify.register(fastifyRBACPlugin(rbac))
```
## Route Protection
### adapter.permission
```typescript
// Single permission
fastify.post('/posts', {
preHandler: rbacHooks.permission('posts:write')
}, async (request, reply) => {
return { message: 'Post created' }
})
```
### adapter.any / adapter.all
```typescript
// Require at least one permission
fastify.get('/admin', {
preHandler: rbacHooks.any('admin:access', 'moderator:access')
}, async (request, reply) => {
return { message: 'Admin panel' }
})
// Require all permissions
fastify.delete('/posts/:id', {
preHandler: rbacHooks.all('posts:delete', 'posts:own')
}, async (request, reply) => {
return { message: 'Post deleted' }
})
```
### requirePermission
```typescript
import { requirePermission } from '@fire-shield/fastify'
fastify.post('/posts', {
preHandler: requirePermission('posts:write', { rbac })
}, async (request, reply) => {
return { message: 'Post created' }
})
```
### requireRole
```typescript
import { requireRole } from '@fire-shield/fastify'
// Single role
fastify.get('/admin/users', {
preHandler: requireRole('admin', { rbac })
}, async (request, reply) => {
return { users: [] }
})
```
### adapter.role
```typescript
fastify.get('/admin/users', {
preHandler: rbacHooks.role('admin')
}, async (request, reply) => {
return { users: [] }
})
```
### requireResourceAction
```typescript
import { requireResourceAction } from '@fire-shield/fastify'
fastify.delete('/users/:id', {
preHandler: requireResourceAction('users', 'delete', { rbac })
}, async (request, reply) => {
return { message: 'User deleted' }
})
```
### adapter.denyPermission / adapter.allowPermission
```typescript
// Deny a permission for the user making this request
fastify.post('/restrict', {
preHandler: rbacHooks.denyPermission('posts:delete')
}, async (request, reply) => {
return { message: 'posts:delete has been denied' }
})
// Remove a previously denied permission
fastify.post('/restore', {
preHandler: rbacHooks.allowPermission('posts:delete')
}, async (request, reply) => {
return { message: 'posts:delete has been restored' }
})
```
### adapter.notDenied
```typescript
fastify.delete('/posts/:id', {
preHandler: [
rbacHooks.notDenied('posts:delete'),
rbacHooks.permission('posts:delete')
]
}, async (request, reply) => {
return { message: 'Post deleted' }
})
```
### Standalone denyPermission / allowPermission / requireNotDenied
```typescript
import { denyPermission, allowPermission, requireNotDenied } from '@fire-shield/fastify'
fastify.post('/restrict', {
preHandler: denyPermission('posts:delete', { rbac })
}, async (request, reply) => {
return { message: 'Permission denied' }
})
```
### adapter.getDeniedPermissions / adapter.isDenied
```typescript
fastify.get('/my-permissions', async (request, reply) => {
const denied = rbacHooks.getDeniedPermissions(request)
const cannotDelete = rbacHooks.isDenied(request, 'posts:delete')
return { denied, cannotDelete }
})
```
## Custom Error Handling
### Default Behavior
```json
{
"statusCode": 403,
"error": "Forbidden",
"message": "Insufficient permissions"
}
```
### Custom Error Handler
```typescript
const rbacHooks = new FastifyRBACAdapter(rbac, {
getUser: (request) => request.user,
onUnauthorized: (result, request, reply) => {
reply.code(403).send({
error: 'Access Denied',
message: result.reason,
requiredPermission: result.reason
})
}
})
```
### Error Hook
```typescript
fastify.setErrorHandler((error, request, reply) => {
if (error.statusCode === 403) {
request.log.warn('RBAC access denied', {
user: request.user?.id,
path: request.url
})
}
reply.send(error)
})
```
## Authentication Integration
### With JWT
```typescript
import fastifyJwt from '@fastify/jwt'
// Register JWT plugin
fastify.register(fastifyJwt, {
secret: 'your-secret-key'
})
// Authentication decorator
fastify.decorate('authenticate', async (request, reply) => {
try {
await request.jwtVerify()
} catch (err) {
reply.send(err)
}
})
// Use authentication and RBAC together
fastify.post('/posts', {
preHandler: [
fastify.authenticate,
rbacHooks.permission('posts:write')
]
}, async (request, reply) => {
return { message: 'Post created' }
})
```
### With Session
```typescript
import fastifySession from '@fastify/session'
import fastifyCookie from '@fastify/cookie'
fastify.register(fastifyCookie)
fastify.register(fastifySession, {
secret: 'a-secret-with-minimum-length-of-32-characters',
cookie: { secure: false }
})
// Attach user from session
fastify.addHook('preHandler', async (request, reply) => {
if (request.session.userId) {
request.user = await getUserById(request.session.userId)
}
})
// Protected route
fastify.delete('/posts/:id', {
preHandler: rbacHooks.permission('posts:delete')
}, async (request, reply) => {
return { message: 'Post deleted' }
})
```
## Programmatic Permission Checks
```typescript
fastify.get('/posts/:id', async (request, reply) => {
const post = await getPost(request.params.id)
// request.authorization is set by the RBAC hook after a successful check
const authorized = (request as any).authorization?.allowed
return post
})
```
## Route Organization
### Grouped Routes
```typescript
// Admin routes plugin
async function adminRoutes(fastify, options) {
// All admin routes require admin role
fastify.addHook('preHandler', rbacHooks.role('admin'))
fastify.get('/users', async (request, reply) => {
return { users: [] }
})
fastify.post('/users', async (request, reply) => {
return { message: 'User created' }
})
}
fastify.register(adminRoutes, { prefix: '/admin' })
```
### Nested Permissions
```typescript
// Posts routes plugin
async function postsRoutes(fastify, options) {
// All routes require read permission
fastify.addHook('preHandler', rbacHooks.permission('posts:read'))
fastify.get('/', async (request, reply) => {
return { posts: [] }
})
// Additional permission for write
fastify.post('/', {
preHandler: rbacHooks.permission('posts:write')
}, async (request, reply) => {
return { message: 'Post created' }
})
// Additional permission for delete
fastify.delete('/:id', {
preHandler: rbacHooks.permission('posts:delete')
}, async (request, reply) => {
return { message: 'Post deleted' }
})
}
fastify.register(postsRoutes, { prefix: '/posts' })
```
## Dynamic Permissions
```typescript
fastify.delete('/posts/:id',
{ preHandler: rbacHooks.permission('posts:delete') },
async (request, reply) => {
const post = await getPost(request.params.id)
// Check if user owns the post
const isOwner = post.authorId === request.user.id
if (!isOwner) {
return reply.code(403).send({ error: 'Forbidden' })
}
await deletePost(request.params.id)
return { message: 'Post deleted' }
}
)
```
## TypeScript Support
```typescript
import { FastifyRequest, FastifyReply } from 'fastify'
import { RBACUser } from '@fire-shield/core'
// Fastify Request is already extended by @fire-shield/fastify:
// request.user?: RBACUser
// Type-safe route handler
fastify.get<{
Params: { id: string }
}>('/posts/:id', async (request, reply) => {
return { id: request.params.id }
})
```
## Best Practices
### 1. Use Hooks for Route Groups
```typescript
// ✅ Good: Apply to all routes in plugin
async function adminRoutes(fastify) {
fastify.addHook('preHandler', rbacHooks.role('admin'))
fastify.get('/users', getUsers)
fastify.post('/users', createUser)
fastify.delete('/users/:id', deleteUser)
}
// ❌ Avoid: Repeat on every route
fastify.get('/admin/users', {
preHandler: rbacHooks.role('admin')
}, getUsers)
fastify.post('/admin/users', {
preHandler: rbacHooks.role('admin')
}, createUser)
```
### 2. Chain Handlers
```typescript
// ✅ Good: Multiple handlers in array
fastify.post('/posts', {
preHandler: [
fastify.authenticate,
rbacHooks.permission('posts:write'),
validatePostData
]
}, createPost)
// ✅ Also good: Single combined handler
fastify.post('/posts', {
preHandler: rbacHooks.permission('posts:write')
}, createPost)
```
### 3. Handle Errors Properly
```typescript
// ✅ Good: Custom error handling
const rbacHooks = new FastifyRBACAdapter(rbac, {
getUser: (request) => request.user,
onUnauthorized: (result, request, reply) => {
request.log.warn({
path: request.url,
user: request.user?.id,
reason: result.reason
}, 'RBAC access denied')
reply.code(403).send({
error: 'Forbidden',
message: 'Insufficient permissions'
})
}
})
```
### 4. Document Routes
```typescript
fastify.post('/posts', {
schema: {
description: 'Create a new post',
tags: ['posts'],
summary: 'Create post',
security: [{ bearerAuth: [] }]
},
preHandler: rbacHooks.permission('posts:write')
}, async (request, reply) => {
return { message: 'Post created' }
})
```
## OpenAPI/Swagger Integration
```typescript
import fastifySwagger from '@fastify/swagger'
import fastifySwaggerUI from '@fastify/swagger-ui'
fastify.register(fastifySwagger, {
openapi: {
info: {
title: 'API Documentation',
version: '1.0.0'
},
components: {
securitySchemes: {
bearerAuth: {
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT'
}
}
}
}
})
fastify.register(fastifySwaggerUI, {
routePrefix: '/documentation'
})
// Document permission requirements
fastify.post('/posts', {
schema: {
description: 'Create a new post (requires posts:write permission)',
tags: ['posts'],
security: [{ bearerAuth: [] }],
response: {
200: {
type: 'object',
properties: {
message: { type: 'string' }
}
},
403: {
type: 'object',
properties: {
error: { type: 'string' }
}
}
}
},
preHandler: rbacHooks.permission('posts:write')
}, async (request, reply) => {
return { message: 'Post created' }
})
```
## Complete Example
```typescript
import Fastify from 'fastify'
import { RBAC } from '@fire-shield/core'
import { FastifyRBACAdapter, fastifyRBACPlugin } from '@fire-shield/fastify'
import fastifyJwt from '@fastify/jwt'
const fastify = Fastify({
logger: true
})
const rbac = new RBAC()
// Setup roles
rbac.createRole('admin', ['*'])
rbac.createRole('editor', ['posts:*', 'comments:*'])
rbac.createRole('viewer', ['posts:read', 'comments:read'])
// JWT plugin
fastify.register(fastifyJwt, {
secret: 'your-secret-key'
})
// RBAC adapter
const rbacHooks = new FastifyRBACAdapter(rbac, {
getUser: (request) => request.user,
onUnauthorized: (result, request, reply) => {
reply.code(403).send({
error: 'Forbidden',
message: result.reason || 'Insufficient permissions'
})
}
})
// Register RBAC plugin (optional, adds fastify.rbac and fastify.authorize decorators)
fastify.register(fastifyRBACPlugin(rbac))
// Authentication decorator
fastify.decorate('authenticate', async (request, reply) => {
try {
await request.jwtVerify()
} catch (err) {
reply.send(err)
}
})
// Public route
fastify.get('/health', async () => {
return { status: 'ok' }
})
// Protected routes
fastify.get('/posts', {
preHandler: [
fastify.authenticate,
rbacHooks.permission('posts:read')
]
}, async () => {
return { posts: [] }
})
fastify.post('/posts', {
preHandler: [
fastify.authenticate,
rbacHooks.permission('posts:write')
]
}, async () => {
return { message: 'Post created' }
})
fastify.delete('/posts/:id', {
preHandler: [
fastify.authenticate,
rbacHooks.permission('posts:delete')
]
}, async () => {
return { message: 'Post deleted' }
})
// Admin routes
async function adminRoutes(fastify) {
fastify.addHook('preHandler', rbacHooks.role('admin'))
fastify.get('/users', async () => {
return { users: [] }
})
fastify.post('/users', async () => {
return { message: 'User created' }
})
}
fastify.register(adminRoutes, { prefix: '/admin' })
fastify.listen({ port: 3000 }, (err) => {
if (err) throw err
console.log('Server running on http://localhost:3000')
})
```
## Next Steps
### Hono Integration
> Source: https://fire-shield.dev/frameworks/hono
# Hono Integration
## Features
## Installation
```bash
npm install @fire-shield/hono@3.1.1 @fire-shield/core@3.1.1 hono
```
## Quick Start
```typescript
import { Hono } from 'hono';
import { RBAC } from '@fire-shield/core';
import { HonoRBACAdapter } from '@fire-shield/hono';
const app = new Hono();
const rbac = new RBAC();
// Setup roles
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);
rbac.createRole('viewer', ['post:read']);
// Create adapter
const rbacMiddleware = new HonoRBACAdapter(rbac);
// Add user to context
app.use('*', async (c, next) => {
c.set('user', { id: 'user-1', roles: ['editor'] });
await next();
});
// Protect routes
app.get('/admin/users',
rbacMiddleware.permission('user:read'),
(c) => {
return c.json({ users: [] });
}
);
export default app;
```
## API
### new HonoRBACAdapter(rbac, options?)
```typescript
interface HonoRBACOptions {
getUser?: (c: Context) => RBACUser;
getPermission?: (c: Context) => string;
getResource?: (c: Context) => string;
getAction?: (c: Context) => string;
onUnauthorized?: (result: AuthorizationResult, c: Context) => Response;
onError?: (error: Error, c: Context) => Response;
}
```
```typescript
const rbacMiddleware = new HonoRBACAdapter(rbac, {
getUser: (c) => c.get('user'),
onUnauthorized: (result, c) => {
return c.json({
error: 'Access Denied',
reason: result.reason
}, 403);
}
});
```
## Middleware Methods
### permission(permission: string)
```typescript
app.get('/admin',
rbacMiddleware.permission('admin:access'),
(c) => c.json({ admin: true })
);
```
### role(role: string)
```typescript
app.get('/admin',
rbacMiddleware.role('admin'),
(c) => c.json({ admin: true })
);
```
### resourceAction(resource: string, action: string)
```typescript
app.delete('/users/:id',
rbacMiddleware.resourceAction('user', 'delete'),
(c) => c.json({ deleted: true })
);
```
### all(...permissions: string[])
```typescript
app.post('/admin/users',
rbacMiddleware.all('user:create', 'user:write'),
(c) => c.json({ created: true })
);
```
### any(...permissions: string[])
```typescript
app.get('/dashboard',
rbacMiddleware.any('admin:access', 'moderator:access'),
(c) => c.json({ dashboard: 'data' })
);
```
### middleware(customOptions: Partial<HonoRBACOptions>)
```typescript
app.get('/api/v1/*',
rbacMiddleware.middleware({
getPermission: (c) => c.req.header('x-required-permission'),
onUnauthorized: (result, c) => c.json({ error: 'Custom error' }, 403)
}),
handler
);
```
## Edge Runtime Examples
### Cloudflare Workers
```typescript
import { Hono } from 'hono';
import { RBAC } from '@fire-shield/core';
import { HonoRBACAdapter } from '@fire-shield/hono';
const app = new Hono();
const rbac = new RBAC();
const rbacMiddleware = new HonoRBACAdapter(rbac);
rbac.createRole('admin', ['*']);
// Extract user from Cloudflare request
app.use('*', async (c, next) => {
const apiKey = c.req.header('x-api-key');
const user = await getUserFromApiKey(apiKey);
c.set('user', user);
await next();
});
// Protected routes
app.get('/admin/*',
rbacMiddleware.role('admin'),
(c) => c.json({ admin: true })
);
export default app;
```
### Deno Deploy
```typescript
import { Hono } from 'hono';
import { RBAC } from '@fire-shield/core';
import { HonoRBACAdapter } from '@fire-shield/hono';
const app = new Hono();
const rbac = new RBAC();
const rbacMiddleware = new HonoRBACAdapter(rbac);
rbac.createRole('admin', ['*']);
app.use('*', async (c, next) => {
const token = c.req.header('authorization')?.replace('Bearer ', '');
const user = await verifyToken(token);
c.set('user', user);
await next();
});
app.get('/admin',
rbacMiddleware.role('admin'),
(c) => c.json({ data: 'admin data' })
);
Deno.serve(app.fetch);
```
### Vercel Edge Functions
```typescript
import { Hono } from 'hono';
import { RBAC } from '@fire-shield/core';
import { HonoRBACAdapter } from '@fire-shield/hono';
const app = new Hono();
const rbac = new RBAC();
const rbacMiddleware = new HonoRBACAdapter(rbac);
rbac.createRole('admin', ['*']);
app.get('/admin',
rbacMiddleware.role('admin'),
(c) => c.json({ admin: true })
);
export default app;
export const config = {
runtime: 'edge',
};
```
## Custom Configuration
### Custom User Extraction
```typescript
const rbacMiddleware = new HonoRBACAdapter(rbac, {
getUser: (c) => {
// Try multiple sources
return c.get('session')?.user || c.get('user') || null;
}
});
```
### Custom Unauthorized Handler
```typescript
const rbacMiddleware = new HonoRBACAdapter(rbac, {
onUnauthorized: (result, c) => {
return c.json({
error: 'Access Denied',
required: result.reason,
userId: result.user?.id,
timestamp: Date.now()
}, 403);
}
});
```
### Custom Error Handler
```typescript
const rbacMiddleware = new HonoRBACAdapter(rbac, {
onError: (error, c) => {
console.error('RBAC Error:', error);
return c.json({
error: 'Internal Server Error',
message: error.message
}, 500);
}
});
```
## Advanced Usage
### Multi-Tenant with Wildcards
```typescript
rbac.createRole('tenant-owner', ['tenant:*']);
app.use('/tenant/:tenantId/*', async (c, next) => {
const tenantId = c.req.param('tenantId');
const user = c.get('user');
// Check tenant-specific permission
if (!rbac.hasPermission(user, `tenant:${tenantId}:access`)) {
return c.json({ error: 'Forbidden' }, 403);
}
await next();
});
// Protected tenant routes
app.get('/tenant/:tenantId/data',
rbacMiddleware.permission('tenant:data:read'),
(c) => {
const tenantId = c.req.param('tenantId');
return c.json({ tenantId, data: [] });
}
);
```
### Multiple Permissions (AND/OR)
```typescript
// User must have BOTH permissions (AND)
app.post('/admin/critical',
rbacMiddleware.all('admin:access', 'critical:write'),
(c) => c.json({ success: true })
);
// User must have AT LEAST ONE permission (OR)
app.get('/dashboard',
rbacMiddleware.any('admin:view', 'moderator:view', 'analyst:view'),
(c) => c.json({ dashboard: 'data' })
);
```
### Dynamic Permission Checking
```typescript
const rbacMiddleware = new HonoRBACAdapter(rbac, {
getPermission: (c) => {
// Extract permission from route metadata
const route = c.req.path;
const method = c.req.method.toLowerCase();
if (route.startsWith('/api/')) {
return `api:${method}`;
}
return undefined;
}
});
// Will check for 'api:post' permission
app.post('/api/data',
rbacMiddleware.middleware({}),
(c) => c.json({ created: true })
);
```
### Resource Ownership
```typescript
app.delete('/posts/:id', async (c) => {
const user = c.get('user');
const postId = c.req.param('id');
const post = await getPost(postId);
// Check ownership
const isOwner = post.authorId === user.id;
const canDelete =
rbac.hasPermission(user, 'post:delete:any') ||
(isOwner && rbac.hasPermission(user, 'post:delete:own'));
if (!canDelete) {
return c.json({ error: 'Forbidden' }, 403);
}
await deletePost(postId);
return c.json({ success: true });
});
```
## Grouping Routes
### Protected Route Group
```typescript
const adminRoutes = new Hono();
// All admin routes require admin role
adminRoutes.use('*', rbacMiddleware.role('admin'));
adminRoutes.get('/users', (c) => c.json({ users: [] }));
adminRoutes.post('/users', (c) => c.json({ created: true }));
adminRoutes.delete('/users/:id', (c) => c.json({ deleted: true }));
// Mount admin routes
app.route('/admin', adminRoutes);
```
### Nested Permissions
```typescript
const apiRoutes = new Hono();
// All API routes require base permission
apiRoutes.use('*', rbacMiddleware.permission('api:access'));
// Additional permissions for specific routes
apiRoutes.get('/data',
rbacMiddleware.permission('api:read'),
(c) => c.json({ data: [] })
);
apiRoutes.post('/data',
rbacMiddleware.permission('api:write'),
(c) => c.json({ created: true })
);
app.route('/api', apiRoutes);
```
## Audit Logging
```typescript
import { BufferedAuditLogger } from '@fire-shield/core';
const auditLogger = new BufferedAuditLogger(
async (events) => {
// Save to KV storage (Cloudflare Workers)
await KV.put('audit-logs', JSON.stringify(events));
// Or send to external service
await fetch('https://api.example.com/audit', {
method: 'POST',
body: JSON.stringify(events)
});
},
{ maxBufferSize: 50, flushIntervalMs: 3000 }
);
const rbac = new RBAC({ auditLogger });
```
## Authentication Integration
### With JWT
```typescript
import { verify } from '@tsndr/cloudflare-worker-jwt';
app.use('*', async (c, next) => {
const token = c.req.header('authorization')?.replace('Bearer ', '');
if (token) {
try {
const payload = await verify(token, 'secret');
c.set('user', {
id: payload.sub,
roles: payload.roles
});
} catch (error) {
return c.json({ error: 'Invalid token' }, 401);
}
}
await next();
});
```
### With API Key
```typescript
app.use('*', async (c, next) => {
const apiKey = c.req.header('x-api-key');
if (apiKey) {
const user = await validateApiKey(apiKey);
c.set('user', user);
}
await next();
});
```
## Error Handling
```typescript
app.onError((err, c) => {
console.error('Error:', err);
if (err.message.includes('Forbidden')) {
return c.json({
error: 'Forbidden',
message: 'You do not have permission to access this resource'
}, 403);
}
return c.json({
error: 'Internal Server Error',
message: err.message
}, 500);
});
```
## TypeScript Support
```typescript
import type { Context } from 'hono';
import type { RBACUser } from '@fire-shield/core';
interface CustomContext extends Context {
Variables: {
user: RBACUser;
};
}
app.get('/admin', (c: CustomContext) => {
const user = c.get('user');
return c.json({ user });
});
```
## Best Practices
### 1. Centralize RBAC Setup
```typescript
// lib/rbac.ts
import { RBAC } from '@fire-shield/core';
import { HonoRBACAdapter } from '@fire-shield/hono';
export const rbac = new RBAC();
export const rbacMiddleware = new HonoRBACAdapter(rbac);
// Setup roles
rbac.createRole('admin', ['*']);
rbac.createRole('editor', ['post:*']);
```
### 2. Use Route Groups
```typescript
// Good: Group protected routes
const adminRoutes = new Hono();
adminRoutes.use('*', rbacMiddleware.role('admin'));
// Avoid: Repeat middleware on every route
app.get('/admin/users', rbacMiddleware.role('admin'), handler);
app.post('/admin/users', rbacMiddleware.role('admin'), handler);
```
### 3. Handle Errors Gracefully
```typescript
app.onError((err, c) => {
console.error('RBAC Error:', err);
return c.json({ error: 'Forbidden' }, 403);
});
```
### 4. Use TypeScript
```typescript
interface User extends RBACUser {
email: string;
name: string;
}
app.use('*', async (c, next) => {
const user: User = await getUser(c);
c.set('user', user);
await next();
});
```
## Next Steps
### GraphQL Integration
> Source: https://fire-shield.dev/frameworks/graphql
# GraphQL Integration
## Features
## Installation
```bash
npm install @fire-shield/graphql@3.1.1 @fire-shield/core@3.1.1 graphql
```
## Quick Start
### 1. Setup RBAC
```typescript
import { RBAC } from '@fire-shield/core';
const rbac = new RBAC();
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);
rbac.createRole('viewer', ['post:read']);
```
### 2. Add Directives to Schema
```graphql
directive @hasPermission(permission: String!) on FIELD_DEFINITION
directive @hasRole(role: String!) on FIELD_DEFINITION
directive @hasAnyPermission(permissions: [String!]!) on FIELD_DEFINITION
directive @hasAllPermissions(permissions: [String!]!) on FIELD_DEFINITION
directive @notDenied(permission: String!) on FIELD_DEFINITION
directive @isDenied(permission: String!) on FIELD_DEFINITION
type Query {
posts: [Post!]! @hasPermission(permission: "post:read")
users: [User!]! @hasPermission(permission: "user:read")
adminStats: AdminStats! @hasRole(role: "admin")
}
type Mutation {
createPost(input: CreatePostInput!): Post! @hasPermission(permission: "post:write")
deletePost(id: ID!): Boolean! @hasPermission(permission: "post:delete")
updateUser(id: ID!, input: UpdateUserInput!): User! @hasPermission(permission: "user:write")
}
type Post {
id: ID!
title: String!
content: String!
# Only editors and admins can see draft posts
draft: Boolean! @hasPermission(permission: "post:edit")
}
```
### 3. Create GraphQL Server
```typescript
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { makeExecutableSchema } from '@graphql-tools/schema';
import {
applyFireShieldDirectives,
fireShieldDirectiveTypeDefs,
} from '@fire-shield/graphql';
let schema = makeExecutableSchema({ typeDefs, resolvers });
schema = applyFireShieldDirectives(schema);
const server = new ApolloServer({ schema });
const { url } = await startStandaloneServer(server, {
context: async ({ req }) => {
const user = await getUserFromRequest(req);
return { rbac, user };
},
});
```
## API
### `applyFireShieldDirectives(schema, config?)`
```typescript
applyFireShieldDirectives(schema: GraphQLSchema, config?: {
hasPermission?: { directiveName?: string };
hasRole?: { directiveName?: string };
hasAnyPermission?: { directiveName?: string };
hasAllPermissions?: { directiveName?: string };
}): GraphQLSchema
```
```typescript
import { applyFireShieldDirectives } from '@fire-shield/graphql';
let schema = makeExecutableSchema({ typeDefs, resolvers });
schema = applyFireShieldDirectives(schema);
```
### Individual Directive Factories
```typescript
import {
createHasPermissionDirective,
createHasRoleDirective,
createHasAnyPermissionDirective,
createHasAllPermissionsDirective,
createNotDeniedDirective,
createIsDeniedDirective,
} from '@fire-shield/graphql';
let schema = makeExecutableSchema({ typeDefs, resolvers });
schema = createHasPermissionDirective()(schema);
schema = createHasRoleDirective()(schema);
schema = createHasAnyPermissionDirective()(schema);
schema = createHasAllPermissionsDirective()(schema);
schema = createNotDeniedDirective()(schema);
schema = createIsDeniedDirective()(schema);
```
### `fireShieldDirectiveTypeDefs`
```typescript
import { fireShieldDirectiveTypeDefs } from '@fire-shield/graphql';
const typeDefs = `
${fireShieldDirectiveTypeDefs}
type Query {
users: [User!]! @hasPermission(permission: "user:read")
}
`;
```
### `GraphQLRBACContext` Interface
```typescript
import type { GraphQLRBACContext } from '@fire-shield/graphql';
interface GraphQLRBACContext {
rbac: RBAC; // Fire Shield RBAC instance
user?: RBACUser; // Current user with roles
}
```
```typescript
interface MyContext extends GraphQLRBACContext {
db: Database;
logger: Logger;
}
```
## Available Directives
### @hasPermission
```graphql
type Query {
users: [User!]! @hasPermission(permission: "user:read")
}
```
### @hasRole
```graphql
type Mutation {
deleteUser(id: ID!): Boolean! @hasRole(role: "admin")
}
```
### @hasAnyPermission
```graphql
type Query {
posts: [Post!]! @hasAnyPermission(permissions: ["post:read", "post:write"])
}
```
### @hasAllPermissions
```graphql
type Mutation {
deletePost(id: ID!): Boolean!
@hasAllPermissions(permissions: ["post:delete", "post:admin"])
}
```
### @notDenied
```graphql
type Query {
sensitiveData: JSON! @notDenied(permission: "data:sensitive")
}
```
### @isDenied
```graphql
type Query {
restrictedMessage: String @isDenied(permission: "data:sensitive")
}
```
## Context Requirements
```typescript
const context = ({ req }) => ({
rbac: myRBACInstance,
user: {
id: req.user.id,
roles: req.user.roles,
// Optional: direct permissions
permissions: req.user.permissions,
},
});
```
## Error Handling
```typescript
{
extensions: {
code: 'UNAUTHENTICATED' | 'FORBIDDEN' | 'RBAC_NOT_CONFIGURED',
requiredPermission?: string,
requiredRole?: string,
requiredPermissions?: string[],
}
}
```
```typescript
const server = new ApolloServer({
schema,
formatError: (error) => {
if (error.extensions?.code === 'FORBIDDEN') {
return {
message: 'You do not have permission to access this resource',
extensions: error.extensions,
};
}
return error;
},
});
```
## Advanced Usage
### Custom Directive Names
```typescript
const schema = applyFireShieldDirectives(baseSchema, {
hasPermission: { directiveName: 'requiresPermission' },
hasRole: { directiveName: 'requiresRole' },
});
```
```graphql
directive @requiresPermission(permission: String!) on FIELD_DEFINITION
directive @requiresRole(role: String!) on FIELD_DEFINITION
type Query {
users: [User!]! @requiresPermission(permission: "user:read")
}
```
### Programmatic Permission Checks
```typescript
const resolvers = {
Query: {
users: (_, __, context: GraphQLRBACContext) => {
// Manual check if needed
if (!context.rbac.hasPermission(context.user, 'user:read')) {
throw new GraphQLError('Permission denied');
}
return fetchUsers();
},
},
};
```
### Dynamic Authorization in Resolvers
```typescript
const resolvers = {
Mutation: {
updatePost: async (parent, { id, input }, context: GraphQLRBACContext) => {
const post = await db.post.findUnique({ where: { id } });
// Users can only edit their own posts unless they're admin
const isOwner = context.user?.id === post.authorId;
const isAdmin = context.user?.roles.includes('admin');
if (!isOwner && !isAdmin) {
throw new GraphQLError('Access Denied', {
extensions: { code: 'FORBIDDEN' },
});
}
return await db.post.update({ where: { id }, data: input });
},
},
};
```
## Usage with Apollo Server
```typescript
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { makeExecutableSchema } from '@graphql-tools/schema';
import {
applyFireShieldDirectives,
fireShieldDirectiveTypeDefs,
} from '@fire-shield/graphql';
const typeDefs = `
${fireShieldDirectiveTypeDefs}
type Query {
posts: [Post!]! @hasPermission(permission: "post:read")
post(id: ID!): Post
}
type Mutation {
createPost(input: CreatePostInput!): Post! @hasPermission(permission: "post:write")
deletePost(id: ID!): Boolean! @hasPermission(permission: "post:delete")
}
`;
let schema = makeExecutableSchema({ typeDefs, resolvers });
schema = applyFireShieldDirectives(schema);
const server = new ApolloServer({ schema });
const { url } = await startStandaloneServer(server, {
context: async ({ req }) => {
const user = await getUserFromToken(req.headers.authorization);
return { rbac, user };
},
});
console.log(`Server ready at ${url}`);
```
## Usage with GraphQL Yoga
```typescript
import { createYoga } from 'graphql-yoga';
import { createServer } from 'node:http';
import { makeExecutableSchema } from '@graphql-tools/schema';
import {
applyFireShieldDirectives,
fireShieldDirectiveTypeDefs,
} from '@fire-shield/graphql';
const typeDefs = `
${fireShieldDirectiveTypeDefs}
type Query {
posts: [Post!]! @hasPermission(permission: "post:read")
}
`;
let schema = makeExecutableSchema({ typeDefs, resolvers });
schema = applyFireShieldDirectives(schema);
const yoga = createYoga({
schema,
context: async ({ request }) => {
const token = request.headers.get('authorization');
const user = await getUserFromToken(token);
return { rbac, user };
},
});
const server = createServer(yoga);
server.listen(4000, () => {
console.log('Server is running on http://localhost:4000/graphql');
});
```
## Field-Level Authorization
```graphql
type User {
id: ID!
username: String!
email: String!
# Only visible to admins
internalNotes: String @hasRole(role: "admin")
# Only visible if user has permission
privateData: JSON @hasPermission(permission: "user:private")
# Only visible with explicit permission
apiKeys: [APIKey!]! @hasPermission(permission: "user:api-keys")
}
```
## Subscription Authorization
```graphql
type Subscription {
postCreated: Post! @hasPermission(permission: "post:subscribe")
adminNotifications: AdminNotification! @hasRole(role: "admin")
}
```
## TypeScript Support
```typescript
import type { GraphQLRBACContext } from '@fire-shield/graphql';
interface MyContext extends GraphQLRBACContext {
db: Database;
logger: Logger;
}
const resolvers = {
Query: {
users: (_, __, context: MyContext) => {
context.rbac.hasPermission(context.user, 'user:read');
context.logger.info('Fetching users');
return context.db.users.findMany();
},
},
};
```
## Best Practices
## Next Steps
### tRPC Integration
> Source: https://fire-shield.dev/frameworks/trpc
# tRPC Integration
## Features
## Installation
```bash
npm install @fire-shield/trpc@3.1.1 @fire-shield/core@3.1.1 @trpc/server
```
## Quick Start
### 1. Setup RBAC
```typescript
// src/server/rbac.ts
import { RBAC } from '@fire-shield/core';
export const rbac = new RBAC();
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);
rbac.createRole('viewer', ['post:read']);
```
### 2. Create RBAC Context
```typescript
// src/server/context.ts
import { inferAsyncReturnType } from '@trpc/server';
import { CreateNextContextOptions } from '@trpc/server/adapters/next';
import { rbac } from './rbac';
export async function createContext({ req, res }: CreateNextContextOptions) {
const user = await getUserFromRequest(req);
return {
req,
res,
rbac,
user
};
}
export type Context = inferAsyncReturnType;
```
### 3. Create Protected Procedures
```typescript
// src/server/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { requirePermission, requireRole } from '@fire-shield/trpc';
import type { Context } from './context';
const t = initTRPC.context().create();
export const router = t.router;
export const publicProcedure = t.procedure;
// Protected procedures
export const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
if (!ctx.user) {
throw new TRPCError({ code: 'UNAUTHORIZED' });
}
return next({ ctx: { ...ctx, user: ctx.user } });
});
// Permission-based procedure
export const permissionProcedure = (permission: string) =>
protectedProcedure.use(requirePermission(permission));
// Role-based procedure
export const roleProcedure = (role: string) =>
protectedProcedure.use(requireRole(role));
```
### 4. Use in Routers
```typescript
// src/server/routers/posts.ts
import { z } from 'zod';
import { router, publicProcedure, permissionProcedure } from '../trpc';
export const postsRouter = router({
// Public: Anyone can list posts
list: publicProcedure.query(async () => {
return await db.post.findMany();
}),
// Protected: Requires 'post:read' permission
getById: permissionProcedure('post:read')
.input(z.object({ id: z.string() }))
.query(async ({ input }) => {
return await db.post.findUnique({ where: { id: input.id } });
}),
// Protected: Requires 'post:write' permission
create: permissionProcedure('post:write')
.input(
z.object({
title: z.string(),
content: z.string()
})
)
.mutation(async ({ input, ctx }) => {
return await db.post.create({
data: {
...input,
authorId: ctx.user.id
}
});
}),
// Protected: Requires 'post:delete' permission
delete: permissionProcedure('post:delete')
.input(z.object({ id: z.string() }))
.mutation(async ({ input }) => {
await db.post.delete({ where: { id: input.id } });
return { success: true };
})
});
```
## API
### requirePermission(permission)
```typescript
export const protectedQuery = publicProcedure.use(requirePermission('resource:read'));
```
### requireRole(role)
```typescript
export const adminQuery = publicProcedure.use(requireRole('admin'));
```
### createRBACMiddleware(options)
```typescript
interface RBACMiddlewareOptions {
getUser?: (ctx: any) => RBACUser | undefined;
getRBAC?: (ctx: any) => RBAC;
onUnauthorized?: (result: AuthorizationResult, ctx: any) => void;
}
```
```typescript
import { createRBACMiddleware } from '@fire-shield/trpc';
const customAuth = createRBACMiddleware({
getUser: (ctx) => ctx.session?.user,
getRBAC: (ctx) => ctx.rbac,
onUnauthorized: (result, ctx) => {
throw new TRPCError({
code: 'FORBIDDEN',
message: result.reason
});
}
});
export const customProcedure = publicProcedure.use(customAuth('permission:check'));
```
## Usage with Next.js
```typescript
// pages/api/trpc/[trpc].ts
import { createNextApiHandler } from '@trpc/server/adapters/next';
import { appRouter } from '@/server/routers/_app';
import { createContext } from '@/server/context';
export default createNextApiHandler({
router: appRouter,
createContext
});
```
```typescript
// src/server/routers/_app.ts
import { router } from '../trpc';
import { postsRouter } from './posts';
import { usersRouter } from './users';
export const appRouter = router({
posts: postsRouter,
users: usersRouter
});
export type AppRouter = typeof appRouter;
```
## Client Usage
```typescript
// src/utils/trpc.ts
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '@/server/routers/_app';
export const trpc = createTRPCNext({
config() {
return {
url: '/api/trpc'
};
}
});
```
```tsx
// pages/posts.tsx
import { trpc } from '@/utils/trpc';
export default function PostsPage() {
// Type-safe queries with automatic auth
const { data: posts } = trpc.posts.list.useQuery();
const createPost = trpc.posts.create.useMutation();
return (
createPost.mutate({
title: 'New Post',
content: 'Content here'
})
}
>
Create Post
{posts?.map((post) => (
{post.title}
))}
);
}
```
## Dynamic Authorization
```typescript
export const postsRouter = router({
update: protectedProcedure
.input(
z.object({
id: z.string(),
title: z.string().optional(),
content: z.string().optional()
})
)
.mutation(async ({ input, ctx }) => {
const post = await db.post.findUnique({ where: { id: input.id } });
// Check if user owns the post or is admin
const canEdit =
post.authorId === ctx.user.id ||
ctx.rbac.hasRole(ctx.user, 'admin') ||
ctx.rbac.hasPermission(ctx.user, 'post:edit-any');
if (!canEdit) {
throw new TRPCError({
code: 'FORBIDDEN',
message: 'You can only edit your own posts'
});
}
return await db.post.update({
where: { id: input.id },
data: input
});
})
});
```
## Role-Based Procedures
```typescript
// Admin-only procedures
export const adminRouter = router({
stats: roleProcedure('admin').query(async () => {
return await getAdminStatistics();
}),
deleteUser: roleProcedure('admin')
.input(z.object({ userId: z.string() }))
.mutation(async ({ input }) => {
await db.user.delete({ where: { id: input.userId } });
return { success: true };
})
});
```
## Multiple Permissions
```typescript
import { TRPCError } from '@trpc/server';
export const multiPermissionProcedure = protectedProcedure.use(async ({ ctx, next }) => {
const requiredPermissions = ['post:write', 'post:publish'];
const hasAll = ctx.rbac.hasAllPermissions(ctx.user, requiredPermissions);
if (!hasAll) {
throw new TRPCError({
code: 'FORBIDDEN',
message: 'Missing required permissions'
});
}
return next({ ctx });
});
```
## Batch Operations with Authorization
```typescript
export const postsRouter = router({
deleteMany: permissionProcedure('post:delete')
.input(z.object({ ids: z.array(z.string()) }))
.mutation(async ({ input }) => {
await db.post.deleteMany({
where: { id: { in: input.ids } }
});
return { deleted: input.ids.length };
})
});
```
## Subscription Authorization
```typescript
export const postsRouter = router({
onPostCreated: permissionProcedure('post:subscribe')
.subscription(() => {
return observable((emit) => {
const onPost = (post: Post) => emit.next(post);
eventEmitter.on('post:created', onPost);
return () => {
eventEmitter.off('post:created', onPost);
};
});
})
});
```
## Error Handling
```typescript
import { TRPCError } from '@trpc/server';
export const permissionProcedureWithError = (permission: string) =>
protectedProcedure.use(async ({ ctx, next }) => {
if (!ctx.rbac.hasPermission(ctx.user, permission)) {
throw new TRPCError({
code: 'FORBIDDEN',
message: `Missing required permission: ${permission}`,
cause: {
permission,
user: ctx.user.id,
roles: ctx.user.roles
}
});
}
return next({ ctx });
});
```
## Nested Routers with Authorization
```typescript
// Admin router - all procedures require admin role
const adminProcedure = roleProcedure('admin');
export const adminRouter = router({
users: router({
list: adminProcedure.query(() => db.user.findMany()),
create: adminProcedure
.input(z.object({ email: z.string().email() }))
.mutation(({ input }) => db.user.create({ data: input })),
delete: adminProcedure
.input(z.object({ id: z.string() }))
.mutation(({ input }) => db.user.delete({ where: { id: input.id } }))
}),
settings: router({
get: adminProcedure.query(() => getSettings()),
update: adminProcedure
.input(z.record(z.any()))
.mutation(({ input }) => updateSettings(input))
})
});
```
## Best Practices
## Complete Example
```typescript
// src/server/rbac.ts
import { RBAC } from '@fire-shield/core';
export const rbac = new RBAC({
enableCache: true,
cacheTTL: 60000
});
rbac.createRole('admin', ['*']);
rbac.createRole('editor', ['post:*', 'category:read']);
rbac.createRole('user', ['post:read', 'post:write-own']);
// src/server/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { requirePermission, requireRole } from '@fire-shield/trpc';
import type { Context } from './context';
const t = initTRPC.context().create();
export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
if (!ctx.user) {
throw new TRPCError({ code: 'UNAUTHORIZED' });
}
return next({ ctx: { ...ctx, user: ctx.user } });
});
export const permissionProcedure = (permission: string) =>
protectedProcedure.use(requirePermission(permission));
export const roleProcedure = (role: string) =>
protectedProcedure.use(requireRole(role));
// src/server/routers/posts.ts
import { z } from 'zod';
import { router, publicProcedure, permissionProcedure } from '../trpc';
export const postsRouter = router({
list: publicProcedure.query(async () => {
return await db.post.findMany({ where: { published: true } });
}),
getById: permissionProcedure('post:read')
.input(z.object({ id: z.string() }))
.query(async ({ input }) => {
return await db.post.findUnique({ where: { id: input.id } });
}),
create: permissionProcedure('post:write')
.input(
z.object({
title: z.string().min(1).max(100),
content: z.string().min(1)
})
)
.mutation(async ({ input, ctx }) => {
return await db.post.create({
data: { ...input, authorId: ctx.user.id }
});
}),
delete: permissionProcedure('post:delete')
.input(z.object({ id: z.string() }))
.mutation(async ({ input }) => {
await db.post.delete({ where: { id: input.id } });
return { success: true };
})
});
// src/server/routers/_app.ts
import { router } from '../trpc';
import { postsRouter } from './posts';
export const appRouter = router({
posts: postsRouter
});
export type AppRouter = typeof appRouter;
```
## Next Steps
============================================================
## Frameworks — Mobile
============================================================
### React Native Integration
> Source: https://fire-shield.dev/frameworks/react-native
# React Native Integration
## Features
## Installation
```bash
npm install @fire-shield/react-native@3.1.1 @fire-shield/core@3.1.1 react react-native
```
## Quick Start
```tsx
import { RBACProvider, useRBAC, Can } from '@fire-shield/react-native';
import { RBAC } from '@fire-shield/core';
// Create RBAC instance
const rbac = new RBAC();
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);
rbac.createRole('viewer', ['post:read']);
// Wrap your app with RBACProvider
export default function App() {
const [user, setUser] = useState({ id: '1', roles: ['editor'] });
return (
);
}
// Use hooks in components
function PostEditor() {
const { can, hasRole } = useRBAC();
return (
{/* Component-based check */}
{/* Hook-based check */}
{can('post:delete') && (
);
}
```
## API
### RBACProvider
```typescript
interface RBACProviderProps {
rbac: RBAC;
user?: RBACUser;
children: React.ReactNode;
}
```
```tsx
```
### useRBAC()
```typescript
{
rbac: RBAC;
user?: RBACUser;
setUser: (user: RBACUser | undefined) => void;
can: (permission: string) => boolean;
cannot: (permission: string) => boolean;
hasRole: (role: string) => boolean;
hasAnyRole: (roles: string[]) => boolean;
hasAllRoles: (roles: string[]) => boolean;
}
```
```tsx
function MyComponent() {
const { can, hasRole, user, setUser } = useRBAC();
const handleLogin = (userData) => {
setUser({ id: userData.id, roles: userData.roles });
};
return (
{can('post:write') &&
);
}
```
### usePermission(permission)
```tsx
function DeleteButton({ postId }) {
const canDelete = usePermission('post:delete');
if (!canDelete) return null;
return deletePost(postId)} />;
}
```
### useRole(role)
```tsx
function AdminBadge() {
const isAdmin = useRole('admin');
if (!isAdmin) return null;
return Admin ;
}
```
## Components
### \
```typescript
interface CanProps {
permission: string;
children: React.ReactNode;
fallback?: React.ReactNode;
}
```
```tsx
No access}>
```
### \
```typescript
interface CannotProps {
permission: string;
children: React.ReactNode;
}
```
```tsx
You cannot delete posts
```
## Persistence with AsyncStorage
```tsx
import { useEffect } from 'react';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { useRBAC } from '@fire-shield/react-native';
function App() {
const { user, setUser } = useRBAC();
// Load user from storage on mount
useEffect(() => {
AsyncStorage.getItem('user').then((data) => {
if (data) {
setUser(JSON.parse(data));
}
});
}, []);
// Save user to storage when it changes
useEffect(() => {
if (user) {
AsyncStorage.setItem('user', JSON.stringify(user));
} else {
AsyncStorage.removeItem('user');
}
}, [user]);
return
);
}
```
### Conditional UI Elements
```tsx
function PostCard({ post }) {
const { can } = useRBAC();
return (
{post.title}
{post.content}
{can('post:write') && (
editPost(post.id)} />
)}
{can('post:delete') && (
deletePost(post.id)} />
)}
);
}
```
### Login/Logout
```tsx
function AuthButtons() {
const { user, setUser } = useRBAC();
const handleLogin = async () => {
const userData = await loginAPI();
setUser({
id: userData.id,
roles: userData.roles,
permissions: userData.permissions
});
};
const handleLogout = () => {
setUser(undefined);
};
return (
{user ? (
);
}
```
## TypeScript
```tsx
import type { RBACUser } from '@fire-shield/core';
interface AppUser extends RBACUser {
name: string;
email: string;
}
function UserProfile() {
const { user } = useRBAC();
return (
{user?.name}
{user?.email}
);
}
```
## Next Steps
### Expo Integration
> Source: https://fire-shield.dev/frameworks/expo
# Expo Integration
## Features
## Installation
```bash
npx expo install @fire-shield/expo@3.1.1 @fire-shield/core@3.1.1
```
## Quick Start
```tsx
import { RBACProvider, useRBAC, Can } from '@fire-shield/expo';
import { RBAC } from '@fire-shield/core';
// Create RBAC instance
const rbac = new RBAC();
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);
export default function App() {
const [user, setUser] = useState({ id: '1', roles: ['editor'] });
return (
);
}
```
## Expo-Specific Features
### 1. Persistent User Storage with AsyncStorage
```tsx
import { usePersistedUser } from '@fire-shield/expo';
function App() {
const [user, setUser] = usePersistedUser('@fire-shield:user');
return (
);
}
```
### 2. Secure Token Storage with SecureStore
```tsx
import { useSecureRBACToken } from '@fire-shield/expo';
function AuthScreen() {
const [token, setToken] = useSecureRBACToken('@fire-shield:token');
const handleLogin = async (credentials) => {
const response = await loginAPI(credentials);
// Store token securely in device keychain/keystore
await setToken(response.token);
// Set user in RBAC
setUser(response.user);
};
return
User: {user?.id}
Roles: {user?.roles.join(', ')}
);
}
```
```
[Fire Shield] Permission Check:
user: user-123
roles: ['editor']
permission: post:write
result: true
```
## API
### usePersistedUser(storageKey?)
```tsx
function App() {
const [user, setUser] = usePersistedUser();
return (
);
}
```
### useSecureRBACToken(tokenKey?)
```tsx
function useAuth() {
const [token, setToken] = useSecureRBACToken();
const { setUser } = useRBAC();
const login = async (credentials) => {
const { token, user } = await loginAPI(credentials);
await setToken(token);
setUser(user);
};
const logout = async () => {
await setToken(null); // Clear token
setUser(undefined);
};
return { login, logout };
}
```
### useRBACDebug(enabled?)
```tsx
function App() {
useRBACDebug(__DEV__);
return
);
}
function AuthScreen() {
const { user, setUser } = useRBAC();
const [token, setToken] = useSecureRBACToken();
const handleLogin = async () => {
// Call your API
const response = await fetch('https://api.example.com/login', {
method: 'POST',
body: JSON.stringify({ username: 'admin', password: 'password' })
});
const data = await response.json();
// Store token securely
await setToken(data.token);
// Set user (automatically persisted)
setUser({
id: data.user.id,
roles: data.user.roles
});
};
const handleLogout = async () => {
await setToken(null);
setUser(undefined);
};
if (!user) {
return (
);
}
return (
Welcome, {user.id}!
Roles: {user.roles.join(', ')}
);
}
```
## EAS Build Configuration
```json
// eas.json
{
"build": {
"production": {
"env": {
"RBAC_CACHE_ENABLED": "true"
}
},
"development": {
"developmentClient": true,
"env": {
"RBAC_DEBUG": "true"
}
}
}
}
```
## Expo Go Compatibility
## Best Practices
## Performance Tips
```tsx
import { useMemo } from 'react';
function PostList() {
const { user, rbac } = useRBAC();
const canCreatePost = useMemo(
() => rbac.hasPermission(user, 'post:write'),
[user, rbac]
);
return (
{canCreatePost &&
);
}
```
## TypeScript
```tsx
import type { RBACUser } from '@fire-shield/core';
interface AppUser extends RBACUser {
email: string;
name: string;
}
const [user, setUser] = usePersistedUser();
```
## Troubleshooting
### SecureStore not available
```
Error: SecureStore is not available on this platform
```
### AsyncStorage quota exceeded
```
Error: AsyncStorage quota exceeded
```
## Next Steps
============================================================
## Tools
============================================================
### CLI Tool
> Source: https://fire-shield.dev/frameworks/cli
# CLI Tool
## Features
## Installation
### Global Installation (Recommended)
```bash
npm install -g @fire-shield/cli@3.1.1
```
```bash
fire-shield --version # 3.1.1
fire-shield info # Show CLI information
```
### Local Installation
```bash
npm install --save-dev @fire-shield/cli@3.1.1
```
```bash
npx fire-shield validate config.json
```
## Commands
### `validate` - Validate Configuration
```bash
fire-shield validate [options]
```
```bash
# Basic validation
fire-shield validate rbac-config.json
# Strict mode (stricter validation rules)
fire-shield validate rbac-config.json --strict
# Verbose output (show config details)
fire-shield validate rbac-config.json --verbose
# Both strict and verbose
fire-shield validate rbac-config.json -s -v
```
```
🔍 Validating RBAC configuration...
✓ Configuration is valid
Validated in 15ms
```
```
🔍 Validating RBAC configuration...
File: /path/to/rbac-config.json
Strict mode: disabled
✓ Configuration is valid
Configuration details:
• Name: my-app-rbac
• Version: 1.0.0
• Permissions: 12
• Roles: 4
Permissions:
• user:read [bit: 1]
• user:write [bit: 2]
• user:delete [bit: 4]
• post:read [bit: 8]
...
Roles:
• admin [level: 10]
Permissions: user:*, post:*
• editor [level: 5]
Permissions: post:read, post:write
...
Validated in 18ms
```
```
🔍 Validating RBAC configuration...
✖ Validation failed
Duplicate permission name: 'user:read' found multiple times
Validated in 12ms
```
### `check` - Check User Permission
```bash
fire-shield check --user --roles --permission [options]
```
```bash
# Check if editor can write posts
fire-shield check config.json -u user123 -r editor -p post:write
# Check with multiple roles
fire-shield check config.json -u admin1 -r admin moderator -p user:delete
# Verbose output
fire-shield check config.json -u user1 -r editor -p post:write --verbose
# Check wildcard permission
fire-shield check config.json -u admin -r admin -p post:delete -v
```
```
🔍 Checking permission...
✓ User has permission "post:write"
```
```
🔍 Checking permission...
Config file: /path/to/config.json
User: user123
Roles: editor
Permission: post:write
✓ User has permission "post:write"
User: user123
Roles: editor
Permission: post:write
Result: ALLOWED
Granted by: editor
```
```
🔍 Checking permission...
✖ User does NOT have permission "user:delete"
```
```
🔍 Checking permission...
Config file: /path/to/config.json
User: user123
Roles: editor
Permission: user:delete
✖ User does NOT have permission "user:delete"
User: user123
Roles: editor
Permission: user:delete
Result: DENIED
```
### `info` - Show CLI Information
```bash
fire-shield info
```
```
🔥 Fire Shield RBAC CLI
Version: 3.1.1
Author: khapu2906
License: DIB
Repository: https://github.com/kentphung92/fire-shield
Available commands:
validate Validate RBAC config file
check Check user permissions
init Initialize new config (coming soon)
info Show CLI information
```
### `init` - Initialize Configuration (Coming Soon)
```bash
fire-shield init [options]
```
## Configuration File Format
```json
{
"name": "my-app-rbac",
"version": "1.0.0",
"permissions": [
{ "name": "user:read", "bit": 1 },
{ "name": "user:write", "bit": 2 },
{ "name": "user:delete", "bit": 4 },
{ "name": "post:read", "bit": 8 },
{ "name": "post:write", "bit": 16 },
{ "name": "post:delete", "bit": 32 }
],
"roles": [
{
"name": "admin",
"permissions": ["user:*", "post:*"],
"level": 10
},
{
"name": "editor",
"permissions": ["post:read", "post:write"],
"level": 5
},
{
"name": "viewer",
"permissions": ["post:read"],
"level": 1
}
]
}
```
## CI/CD Integration
### GitHub Actions
```yaml
name: Validate RBAC Config
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install Fire Shield CLI
run: npm install -g @fire-shield/cli
- name: Validate RBAC configuration
run: fire-shield validate config/rbac.json --strict
- name: Test admin permissions
run: fire-shield check config/rbac.json -u admin -r admin -p user:delete
```
### GitLab CI
```yaml
validate-rbac:
image: node:18
stage: test
script:
- npm install -g @fire-shield/cli
- fire-shield validate config/rbac.json --strict
- fire-shield check config/rbac.json -u admin -r admin -p user:delete
```
### Pre-commit Hook
```bash
#!/bin/bash
# .git/hooks/pre-commit
echo "Validating RBAC configuration..."
npx @fire-shield/cli validate config/rbac.json --strict
if [ $? -ne 0 ]; then
echo "❌ RBAC validation failed. Commit aborted."
exit 1
fi
echo "✅ RBAC validation passed"
```
### npm Scripts
```json
{
"scripts": {
"rbac:validate": "fire-shield validate config/rbac.json",
"rbac:validate:strict": "fire-shield validate config/rbac.json --strict",
"rbac:check:admin": "fire-shield check config/rbac.json -u admin -r admin -p user:delete",
"pretest": "npm run rbac:validate"
}
}
```
## Use Cases
### 1. Validate Before Deployment
```bash
# In deployment script
fire-shield validate config/production-rbac.json --strict
if [ $? -eq 0 ]; then
echo "✅ RBAC config valid, proceeding with deployment"
# Deploy application
else
echo "❌ RBAC config invalid, deployment aborted"
exit 1
fi
```
### 2. Test Permission Logic
```bash
# Test if new role has correct permissions
fire-shield check config.json -u test-user -r new-role -p feature:access -v
# Test admin permissions
fire-shield check config.json -u admin1 -r admin -p user:delete -v
fire-shield check config.json -u admin1 -r admin -p post:delete -v
```
### 3. Debug Permission Issues
```bash
# Check why user can't access feature
fire-shield check config.json -u user123 -r editor viewer -p feature:write --verbose
# Validate config to find issues
fire-shield validate config.json --verbose
```
### 4. Automated Testing
```bash
#!/bin/bash
# test-permissions.sh
echo "Testing permission scenarios..."
# Test 1: Admin should have all permissions
fire-shield check config.json -u admin -r admin -p user:delete
fire-shield check config.json -u admin -r admin -p post:delete
# Test 2: Editor should only write posts
fire-shield check config.json -u editor -r editor -p post:write
! fire-shield check config.json -u editor -r editor -p user:delete
# Test 3: Viewer should only read
fire-shield check config.json -u viewer -r viewer -p post:read
! fire-shield check config.json -u viewer -r viewer -p post:write
echo "✅ All tests passed"
```
## Common Errors
### File Not Found
```bash
fire-shield validate non-existent.json
```
```
✖ File not found: /path/to/non-existent.json
```
### Invalid JSON
```bash
fire-shield validate invalid.json
```
```
✖ Invalid JSON
Unexpected token } in JSON at position 123
```
### Duplicate Permissions
```json
{
"permissions": [
{ "name": "user:read", "bit": 1 },
{ "name": "user:read", "bit": 2 } // Duplicate!
]
}
```
```
✖ Validation failed
Duplicate permission name: 'user:read'
```
### Undefined Permission in Role
```json
{
"permissions": [
{ "name": "user:read", "bit": 1 }
],
"roles": [
{
"name": "admin",
"permissions": ["user:write"] // Not defined!
}
]
}
```
```
✖ Validation failed
Role 'admin' references undefined permission: 'user:write'
```
### Missing Required Options
```bash
fire-shield check config.json -u user1 -p post:write
# Missing --roles option
```
```
✖ At least one role is required (--roles ...)
```
## Tips and Best Practices
### 1. Use Strict Mode in Production
```bash
# Development
fire-shield validate config.json
# Production
fire-shield validate config.json --strict
```
### 2. Version Your Config Files
```json
{
"name": "my-app-rbac",
"version": "2.1.0", // Track changes
"permissions": [...]
}
```
### 3. Use Verbose Mode for Debugging
```bash
fire-shield validate config.json --verbose
fire-shield check config.json -u user1 -r editor -p post:write --verbose
```
### 4. Wildcard Permissions are Validated
```json
{
"roles": [
{
"name": "admin",
"permissions": ["user:*"] // ✅ Valid
}
]
}
```
### 5. Test in CI/CD
```yaml
- run: fire-shield validate config/rbac.json --strict
```
### 6. Document Permission Checks
```bash
# Document expected results in test scripts
echo "Admin should delete users"
fire-shield check config.json -u admin -r admin -p user:delete
echo "Editor should NOT delete users"
! fire-shield check config.json -u editor -r editor -p user:delete
```
## Programmatic Usage
```typescript
import { validateCommand, checkCommand } from '@fire-shield/cli';
// Validate config
try {
await validateCommand('config.json', {
strict: true,
verbose: true
});
console.log('Config valid!');
} catch (error) {
console.error('Config invalid:', error);
}
// Check permission
try {
await checkCommand('config.json', {
user: 'user123',
roles: ['editor'],
permission: 'post:write',
verbose: false
});
console.log('Permission granted');
} catch (error) {
console.error('Permission denied');
}
```
## Troubleshooting
### Command Not Found
```bash
fire-shield: command not found
```
### Permission Denied
```bash
EACCES: permission denied
```
```bash
sudo npm install -g @fire-shield/cli
# or
npm install --save-dev @fire-shield/cli
```
### Version Mismatch
```bash
npm list @fire-shield/cli
npm list @fire-shield/core
```
```bash
npm install -g @fire-shield/cli@latest
npm install @fire-shield/core@latest
```
## Next Steps
## Support
### MCP (Model Context Protocol) Integration
> Source: https://fire-shield.dev/frameworks/mcp
# MCP (Model Context Protocol) Integration
## Features
## What is MCP?
## Installation
```bash
npm install @fire-shield/mcp@3.1.1 @fire-shield/core@3.1.1 @modelcontextprotocol/sdk
```
## Quick Start
### 1. Create MCP Server
```typescript
import { RBAC } from '@fire-shield/core';
import { createMCPServer } from '@fire-shield/mcp';
// Initialize RBAC
const rbac = new RBAC();
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);
rbac.createRole('viewer', ['post:read']);
// Create MCP server
const mcpServer = await createMCPServer({
rbac,
serverName: 'fire-shield-rbac',
serverVersion: '3.1.1',
debug: true
});
// Server is now running and listening for MCP requests
```
### 2. Configure AI Client (Claude Desktop)
```json
{
"mcpServers": {
"fire-shield": {
"command": "node",
"args": ["/path/to/your/mcp-server.js"]
}
}
}
```
### 3. Use in AI Conversations
## Available MCP Tools
### 1. `check_permission` - Check User Permission
```typescript
{
userId: string; // User ID
roles: string[]; // User roles
permission: string; // Permission to check
}
```
```json
{
"userId": "user123",
"roles": ["editor"],
"permission": "post:write"
}
```
```json
{
"hasPermission": true,
"allowed": true,
"reason": "Permission granted",
"userId": "user123",
"roles": ["editor"],
"permission": "post:write"
}
```
### 2. `check_role` - Check User Role
```typescript
{
userId: string; // User ID
roles: string[]; // User roles
role: string; // Role to check
}
```
```json
{
"userId": "user123",
"roles": ["editor", "viewer"],
"role": "editor"
}
```
```json
{
"hasRole": true,
"userId": "user123",
"roles": ["editor", "viewer"],
"role": "editor"
}
```
### 3. `list_permissions` - List User Permissions
```typescript
{
userId: string; // User ID
roles: string[]; // User roles
}
```
```json
{
"userId": "user123",
"roles": ["editor"]
}
```
```json
{
"userId": "user123",
"roles": ["editor"],
"permissions": ["post:read", "post:write"]
}
```
### 4. `deny_permission` - Deny Permission
```typescript
{
userId: string; // User ID
permission: string; // Permission to deny
}
```
```json
{
"userId": "user123",
"permission": "post:delete"
}
```
```json
{
"success": true,
"message": "Permission 'post:delete' denied for user user123",
"userId": "user123",
"permission": "post:delete"
}
```
### 5. `allow_permission` - Allow Permission
```typescript
{
userId: string; // User ID
permission: string; // Permission to allow
}
```
```json
{
"userId": "user123",
"permission": "post:delete"
}
```
```json
{
"success": true,
"message": "Permission 'post:delete' allowed for user user123",
"userId": "user123",
"permission": "post:delete"
}
```
### 6. `get_denied_permissions` - Get Denied Permissions
```typescript
{
userId: string; // User ID
}
```
```json
{
"userId": "user123"
}
```
```json
{
"userId": "user123",
"deniedPermissions": ["post:delete", "user:write"]
}
```
### 7. `list_roles` - List All Roles
```typescript
{} // No parameters required
```
```json
{
"roles": ["admin", "editor", "viewer"]
}
```
### 8. `get_role_permissions` - Get Role Permissions
```typescript
{
role: string; // Role name
}
```
```json
{
"role": "editor"
}
```
```json
{
"role": "editor",
"permissions": ["post:read", "post:write"]
}
```
## API Reference
### FireShieldMCPServer
```typescript
class FireShieldMCPServer {
constructor(options: FireShieldMCPOptions);
async start(): Promise;
getServer(): Server;
}
```
### FireShieldMCPOptions
```typescript
interface FireShieldMCPOptions {
rbac: RBAC; // RBAC instance
serverName?: string; // Server name (default: 'fire-shield-rbac')
serverVersion?: string; // Server version (default: '3.1.1')
debug?: boolean; // Enable debug logging (default: false)
}
```
### createMCPServer()
```typescript
async function createMCPServer(
options: FireShieldMCPOptions
): Promise
```
### startStandalone()
```typescript
async function startStandalone(config: PresetConfig): Promise
```
## Usage Examples
### Standalone Server
```typescript
// mcp-server.ts
import { RBAC } from '@fire-shield/core';
import { createMCPServer } from '@fire-shield/mcp';
async function main() {
// Initialize RBAC with your configuration
const rbac = new RBAC();
// Define roles
rbac.createRole('admin', ['*']);
rbac.createRole('editor', ['post:read', 'post:write', 'post:edit']);
rbac.createRole('viewer', ['post:read']);
// Create and start MCP server
const server = await createMCPServer({
rbac,
serverName: 'my-app-rbac',
serverVersion: '1.0.0',
debug: process.env.NODE_ENV === 'development'
});
console.error('MCP server started successfully');
}
main().catch(console.error);
```
```bash
# Build
npx tsc mcp-server.ts
# Run
node mcp-server.js
```
### Load from Config File
```typescript
// mcp-server-config.ts
import { RBAC } from '@fire-shield/core';
import { createMCPServer } from '@fire-shield/mcp';
import { readFileSync } from 'fs';
async function main() {
// Load RBAC configuration from file
const config = JSON.parse(readFileSync('./rbac-config.json', 'utf-8'));
const rbac = new RBAC({ preset: config });
// Create MCP server
await createMCPServer({
rbac,
serverName: config.name || 'fire-shield-rbac',
serverVersion: config.version || '1.0.0'
});
}
main().catch(console.error);
```
```json
{
"name": "my-app-rbac",
"version": "1.0.0",
"permissions": [
{ "name": "user:read", "bit": 1 },
{ "name": "user:write", "bit": 2 },
{ "name": "post:read", "bit": 4 },
{ "name": "post:write", "bit": 8 }
],
"roles": [
{ "name": "admin", "permissions": ["user:*", "post:*"] },
{ "name": "editor", "permissions": ["post:read", "post:write"] },
{ "name": "viewer", "permissions": ["post:read"] }
]
}
```
### Integration with Express API
```typescript
import express from 'express';
import { RBAC } from '@fire-shield/core';
import { createMCPServer } from '@fire-shield/mcp';
// Shared RBAC instance
const rbac = new RBAC();
rbac.createRole('admin', ['*']);
rbac.createRole('editor', ['post:*']);
// Start Express API
const app = express();
app.use(express.json());
app.post('/api/check-permission', (req, res) => {
const { user, permission } = req.body;
const hasPermission = rbac.hasPermission(user, permission);
res.json({ hasPermission });
});
app.listen(3000, () => {
console.log('API running on port 3000');
});
// Start MCP server (shares the same RBAC instance)
createMCPServer({
rbac,
debug: true
}).then(() => {
console.error('MCP server started');
});
```
## Claude Desktop Configuration
### Basic Configuration
```json
{
"mcpServers": {
"fire-shield": {
"command": "node",
"args": ["/absolute/path/to/mcp-server.js"]
}
}
}
```
### With Environment Variables
```json
{
"mcpServers": {
"fire-shield": {
"command": "node",
"args": ["/path/to/mcp-server.js"],
"env": {
"NODE_ENV": "production",
"RBAC_CONFIG": "/path/to/rbac-config.json"
}
}
}
}
```
### Using npx
```json
{
"mcpServers": {
"fire-shield": {
"command": "npx",
"args": [
"-y",
"tsx",
"/path/to/mcp-server.ts"
]
}
}
}
```
## AI Conversation Examples
### Example 1: Check Permission
```json
{
"userId": "john",
"roles": ["editor"],
"permission": "post:write"
}
```
### Example 2: List Permissions
```json
{
"role": "editor"
}
```
### Example 3: Deny Permission
```json
{
"userId": "alice",
"permission": "post:delete"
}
```
### Example 4: Audit Permissions
```json
{
"userId": "bob",
"roles": ["editor", "moderator"]
}
```
## Integration with Continue
### Configuration
```json
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-server.js"]
}
}
]
}
}
```
### Usage
## Debugging
### Enable Debug Mode
```typescript
const server = await createMCPServer({
rbac,
debug: true // Enables debug logging to stderr
});
```
### View MCP Messages
### Test Tools Manually
```bash
npm install -g @modelcontextprotocol/inspector
# Inspect your server
mcp-inspector node mcp-server.js
```
## Best Practices
### 1. Separate MCP Server Process
```typescript
// Good: Dedicated MCP server
// mcp-server.ts
createMCPServer({ rbac });
// app.ts
// Your main application
```
### 2. Share Configuration
```typescript
// config/rbac.ts
export const rbacConfig = {
permissions: [...],
roles: [...]
};
// app.ts
const rbac = new RBAC({ preset: rbacConfig });
// mcp-server.ts
const rbac = new RBAC({ preset: rbacConfig });
```
### 3. Validate User Input
```typescript
const allowedUsers = ['user1', 'user2', 'user3'];
if (!allowedUsers.includes(userId)) {
throw new Error('Invalid user ID');
}
```
### 4. Audit MCP Operations
```typescript
const rbac = new RBAC({
auditLogger: new BufferedAuditLogger(async (logs) => {
console.log('MCP Audit:', logs);
await database.saveLogs(logs);
})
});
```
### 5. Secure Your MCP Server
## Limitations
## Troubleshooting
### MCP Server Not Starting
```bash
npm install @modelcontextprotocol/sdk
```
### Tools Not Appearing in Claude
### Permission Check Returning Wrong Results
## Performance
## Next Steps
## Resources
============================================================
## Examples
============================================================
### Basic Usage Examples
> Source: https://fire-shield.dev/examples/basic-usage
# Basic Usage Examples
## Simple Blog Application
```typescript
import { RBAC } from '@fire-shield/core'
const rbac = new RBAC()
// Define roles
rbac.createRole('admin', [
'posts:*',
'users:*',
'comments:*',
'settings:*'
])
rbac.createRole('author', [
'posts:create',
'posts:read',
'posts:update:own',
'posts:delete:own',
'comments:read'
])
rbac.createRole('viewer', [
'posts:read',
'comments:read'
])
// Set hierarchy
rbac.setRoleHierarchy({
admin: ['author', 'viewer'],
author: ['viewer']
})
// Check permissions
const admin = { id: '1', roles: ['admin'] }
const author = { id: '2', roles: ['author'] }
const viewer = { id: '3', roles: ['viewer'] }
// Admin can do everything
console.log(rbac.hasPermission(admin, 'posts:delete')) // true
console.log(rbac.hasPermission(admin, 'users:manage')) // true
// Author can create and edit
console.log(rbac.hasPermission(author, 'posts:create')) // true
console.log(rbac.hasPermission(author, 'posts:delete')) // false
// Viewer can only read
console.log(rbac.hasPermission(viewer, 'posts:read')) // true
console.log(rbac.hasPermission(viewer, 'posts:create')) // false
```
## E-Commerce Application
```typescript
const rbac = new RBAC()
// Customer role
rbac.createRole('customer', [
'products:read',
'cart:*',
'orders:create',
'orders:read:own',
'profile:update:own'
])
// Store manager
rbac.createRole('manager', [
'products:*',
'orders:read',
'orders:update',
'inventory:manage',
'reports:read'
])
// Admin
rbac.createRole('admin', [
'*' // All permissions
])
// Set hierarchy
rbac.setRoleHierarchy({
admin: ['manager'],
manager: ['customer']
})
// Usage
const customer = { id: 'cust-1', roles: ['customer'] }
const manager = { id: 'mgr-1', roles: ['manager'] }
// Customer can manage cart
console.log(rbac.hasPermission(customer, 'cart:add')) // true
console.log(rbac.hasPermission(customer, 'cart:checkout')) // true
// Manager can manage products
console.log(rbac.hasPermission(manager, 'products:create')) // true
console.log(rbac.hasPermission(manager, 'inventory:manage')) // true
// Manager inherits customer permissions
console.log(rbac.hasPermission(manager, 'cart:add')) // true
```
## Multi-Tenant SaaS
```typescript
const rbac = new RBAC()
// Workspace owner
rbac.createRole('workspace-owner', [
'workspace:*',
'members:*',
'billing:*',
'data:*'
])
// Workspace admin
rbac.createRole('workspace-admin', [
'workspace:read',
'workspace:update',
'members:invite',
'members:remove',
'data:*'
])
// Workspace member
rbac.createRole('workspace-member', [
'workspace:read',
'data:read',
'data:create',
'data:update:own'
])
// Guest
rbac.createRole('workspace-guest', [
'workspace:read',
'data:read'
])
rbac.setRoleHierarchy({
'workspace-owner': ['workspace-admin'],
'workspace-admin': ['workspace-member'],
'workspace-member': ['workspace-guest']
})
// Check tenant-specific permissions
const owner = { id: '1', roles: ['workspace-owner'] }
const member = { id: '2', roles: ['workspace-member'] }
console.log(rbac.hasPermission(owner, 'billing:update')) // true
console.log(rbac.hasPermission(member, 'billing:update')) // false
console.log(rbac.hasPermission(member, 'data:create')) // true
```
## Content Management System
```typescript
const rbac = new RBAC()
// Super admin
rbac.createRole('super-admin', ['*'])
// Content admin
rbac.createRole('content-admin', [
'content:*',
'media:*',
'categories:*'
])
// Editor
rbac.createRole('editor', [
'content:read',
'content:create',
'content:update',
'content:publish',
'media:read',
'media:upload'
])
// Contributor
rbac.createRole('contributor', [
'content:read',
'content:create',
'content:update:own',
'media:read'
])
// Reviewer
rbac.createRole('reviewer', [
'content:read',
'content:review',
'content:comment'
])
rbac.setRoleHierarchy({
'super-admin': ['content-admin'],
'content-admin': ['editor'],
'editor': ['contributor']
})
const editor = { id: '1', roles: ['editor'] }
const contributor = { id: '2', roles: ['contributor'] }
// Editor can publish
console.log(rbac.hasPermission(editor, 'content:publish')) // true
// Contributor cannot publish
console.log(rbac.hasPermission(contributor, 'content:publish')) // false
// Both can create
console.log(rbac.hasPermission(editor, 'content:create')) // true
console.log(rbac.hasPermission(contributor, 'content:create')) // true
```
## API Gateway
```typescript
const rbac = new RBAC()
// Free tier
rbac.createRole('api-free', [
'api:v1:read',
'api:ratelimit:basic' // 100 req/hour
])
// Pro tier
rbac.createRole('api-pro', [
'api:v1:*',
'api:v2:read',
'api:ratelimit:pro', // 1000 req/hour
'api:analytics:basic'
])
// Enterprise tier
rbac.createRole('api-enterprise', [
'api:*',
'api:ratelimit:unlimited',
'api:analytics:*',
'api:priority:support'
])
rbac.setRoleHierarchy({
'api-enterprise': ['api-pro'],
'api-pro': ['api-free']
})
const freeUser = { id: '1', roles: ['api-free'] }
const proUser = { id: '2', roles: ['api-pro'] }
const enterpriseUser = { id: '3', roles: ['api-enterprise'] }
// Check API access
console.log(rbac.hasPermission(freeUser, 'api:v1:read')) // true
console.log(rbac.hasPermission(freeUser, 'api:v2:read')) // false
console.log(rbac.hasPermission(proUser, 'api:v1:write')) // true
console.log(rbac.hasPermission(proUser, 'api:v2:read')) // true
console.log(rbac.hasPermission(enterpriseUser, 'api:v2:write')) // true
```
## Resource Ownership
```typescript
const rbac = new RBAC()
rbac.createRole('user', [
'posts:read',
'posts:create',
'posts:update:own',
'posts:delete:own',
'comments:create',
'comments:update:own'
])
rbac.createRole('moderator', [
'posts:read',
'posts:update',
'comments:*'
])
// Check ownership in application logic
function canEditPost(user, post) {
// User owns the post
if (post.authorId === user.id) {
return rbac.hasPermission(user, 'posts:update:own')
}
// User is moderator
return rbac.hasPermission(user, 'posts:update')
}
// Example usage
const user = { id: 'user-1', roles: ['user'] }
const moderator = { id: 'mod-1', roles: ['moderator'] }
const myPost = { id: 'post-1', authorId: 'user-1' }
const otherPost = { id: 'post-2', authorId: 'user-2' }
console.log(canEditPost(user, myPost)) // true (owns post)
console.log(canEditPost(user, otherPost)) // false (doesn't own)
console.log(canEditPost(moderator, otherPost)) // true (moderator)
```
## Dynamic Role Assignment
```typescript
const rbac = new RBAC()
rbac.createRole('free', ['app:basic'])
rbac.createRole('pro', ['app:basic', 'app:pro'])
rbac.createRole('enterprise', ['app:*'])
// Assign role based on subscription
function getUserWithRoles(user, subscription) {
const roles = ['free'] // Default role
if (subscription.plan === 'pro') {
roles.push('pro')
} else if (subscription.plan === 'enterprise') {
roles.push('enterprise')
}
// Add time-based roles
if (subscription.trial && subscription.trialEndsAt > new Date()) {
roles.push('trial')
}
return {
...user,
roles
}
}
// Usage
const subscription = { plan: 'pro', trial: false }
const userWithRoles = getUserWithRoles(
{ id: '1', email: 'user@example.com' },
subscription
)
console.log(rbac.hasPermission(userWithRoles, 'app:pro')) // true
```
## Audit Logging
```typescript
import { RBAC, BufferedAuditLogger } from '@fire-shield/core'
const auditLogger = new BufferedAuditLogger(
async (logs) => {
// Save to database
await db.auditLogs.insertMany(logs)
// Send to logging service
await analyticsService.track('audit_logs', {
count: logs.length,
events: logs
})
},
{
maxBufferSize: 50,
flushIntervalMs: 3000
}
)
const rbac = new RBAC({ auditLogger })
// All permission checks are automatically logged
rbac.hasPermission(user, 'posts:delete')
// Logs: {
// timestamp: Date,
// userId: 'user-1',
// action: 'permission_check',
// permission: 'posts:delete',
// result: true/false
// }
// Manually flush logs
await auditLogger.flush()
```
## Testing RBAC
```typescript
import { describe, it, expect } from 'vitest'
import { RBAC } from '@fire-shield/core'
describe('RBAC Configuration', () => {
const rbac = new RBAC()
beforeEach(() => {
rbac.createRole('admin', ['*'])
rbac.createRole('editor', ['posts:*'])
rbac.createRole('viewer', ['posts:read'])
rbac.setRoleHierarchy({
admin: ['editor'],
editor: ['viewer']
})
})
it('admin should have all permissions', () => {
const admin = { id: '1', roles: ['admin'] }
expect(rbac.hasPermission(admin, 'posts:write')).toBe(true)
expect(rbac.hasPermission(admin, 'users:delete')).toBe(true)
expect(rbac.hasPermission(admin, 'anything')).toBe(true)
})
it('editor should inherit viewer permissions', () => {
const editor = { id: '2', roles: ['editor'] }
expect(rbac.hasPermission(editor, 'posts:read')).toBe(true)
expect(rbac.hasPermission(editor, 'posts:write')).toBe(true)
})
it('viewer should only read', () => {
const viewer = { id: '3', roles: ['viewer'] }
expect(rbac.hasPermission(viewer, 'posts:read')).toBe(true)
expect(rbac.hasPermission(viewer, 'posts:write')).toBe(false)
})
})
```
## Next Steps
### Role Hierarchy Examples
> Source: https://fire-shield.dev/examples/role-hierarchy
# Role Hierarchy Examples
## Corporate Hierarchy
```typescript
import { RBAC, RBACBuilder } from '@fire-shield/core';
// Build corporate hierarchy
const rbac = new RBACBuilder()
// Executive Level
.addRole('ceo', ['*'], {
level: 100,
description: 'Chief Executive Officer - Full access'
})
.addRole('cto', ['technology:*', 'team:*'], {
level: 90,
description: 'Chief Technology Officer'
})
.addRole('cfo', ['finance:*', 'team:*'], {
level: 90,
description: 'Chief Financial Officer'
})
// Management Level
.addRole('director', ['department:*', 'team:manage'], {
level: 50,
description: 'Department Director'
})
.addRole('manager', ['team:*', 'project:*'], {
level: 30,
description: 'Team Manager'
})
.addRole('team-lead', ['project:*', 'code:*'], {
level: 20,
description: 'Technical Team Lead'
})
// Individual Contributors
.addRole('senior-engineer', ['code:*', 'review:*'], {
level: 15,
description: 'Senior Engineer'
})
.addRole('engineer', ['code:read', 'code:write'], {
level: 10,
description: 'Engineer'
})
.addRole('junior-engineer', ['code:read'], {
level: 5,
description: 'Junior Engineer'
})
.addRole('intern', ['code:read'], {
level: 1,
description: 'Intern - Read-only access'
})
.build();
// Usage examples
const ceo = { id: 'ceo-1', roles: ['ceo'] };
const manager = { id: 'mgr-1', roles: ['manager'] };
const engineer = { id: 'eng-1', roles: ['engineer'] };
const intern = { id: 'int-1', roles: ['intern'] };
// CEO can act as anyone
console.log(rbac.canActAsRole('ceo', 'intern')); // true
console.log(rbac.canActAsRole('ceo', 'manager')); // true
// Manager can act as engineers
console.log(rbac.canActAsRole('manager', 'engineer')); // true
console.log(rbac.canActAsRole('manager', 'intern')); // true
// Engineer cannot act as manager
console.log(rbac.canActAsRole('engineer', 'manager')); // false
// Permission checks
console.log(rbac.hasPermission(ceo, 'code:delete')); // true (has *)
console.log(rbac.hasPermission(manager, 'team:manage')); // true
console.log(rbac.hasPermission(intern, 'code:write')); // false
```
## Permission Delegation System
```typescript
interface DelegationRequest {
delegatorId: string;
delegateeId: string;
permission: string;
duration?: number; // milliseconds
}
class PermissionDelegationSystem {
constructor(private rbac: RBAC) {}
delegate(request: DelegationRequest): boolean {
const delegator = this.getUser(request.delegatorId);
const delegatee = this.getUser(request.delegateeId);
// Check if delegator has the permission
if (!this.rbac.hasPermission(delegator, request.permission)) {
console.log('Delegator does not have this permission');
return false;
}
// Check hierarchy - delegator must be higher level
const canDelegate = this.canDelegateToUser(delegator, delegatee);
if (!canDelegate) {
console.log('Delegator cannot delegate to this user (insufficient level)');
return false;
}
// Grant temporary permission
this.grantTemporaryPermission(
delegatee,
request.permission,
request.duration
);
return true;
}
private canDelegateToUser(delegator: RBACUser, delegatee: RBACUser): boolean {
const hierarchy = this.rbac.getRoleHierarchy();
for (const delegatorRole of delegator.roles) {
for (const delegateeRole of delegatee.roles) {
const delegatorLevel = hierarchy.getRoleLevel(delegatorRole);
const delegateeLevel = hierarchy.getRoleLevel(delegateeRole);
if (delegatorLevel > delegateeLevel) {
return true;
}
}
}
return false;
}
private grantTemporaryPermission(
user: RBACUser,
permission: string,
duration?: number
): void {
// Add permission to user
if (!user.permissions) {
user.permissions = [];
}
user.permissions.push(permission);
// Auto-revoke after duration
if (duration) {
setTimeout(() => {
this.revokePermission(user, permission);
}, duration);
}
}
private revokePermission(user: RBACUser, permission: string): void {
if (user.permissions) {
user.permissions = user.permissions.filter(p => p !== permission);
}
}
private getUser(userId: string): RBACUser {
// Fetch from database
return { id: userId, roles: [] };
}
}
// Usage
const delegationSystem = new PermissionDelegationSystem(rbac);
const admin = { id: 'admin-1', roles: ['admin'] };
const manager = { id: 'mgr-1', roles: ['manager'] };
// Admin delegates permission to manager for 1 hour
delegationSystem.delegate({
delegatorId: 'admin-1',
delegateeId: 'mgr-1',
permission: 'users:delete',
duration: 3600000 // 1 hour
});
```
## Approval Workflow System
```typescript
interface ApprovalRequest {
id: string;
requesterId: string;
requesterRole: string;
action: string;
resource: string;
status: 'pending' | 'approved' | 'rejected';
approvers: Array<{
userId: string;
level: number;
status: 'pending' | 'approved' | 'rejected';
timestamp?: number;
}>;
}
class ApprovalWorkflow {
constructor(private rbac: RBAC) {}
createRequest(
requesterId: string,
requesterRole: string,
action: string,
resource: string
): ApprovalRequest {
const hierarchy = this.rbac.getRoleHierarchy();
const requesterLevel = hierarchy.getRoleLevel(requesterRole);
// Determine required approval levels
const approvalLevels = this.getRequiredApprovalLevels(action);
// Find approvers at each level
const approvers = approvalLevels
.filter(level => level > requesterLevel)
.map(level => ({
userId: this.findUserAtLevel(level),
level,
status: 'pending' as const
}));
return {
id: `req-${Date.now()}`,
requesterId,
requesterRole,
action,
resource,
status: 'pending',
approvers
};
}
approve(request: ApprovalRequest, approverId: string): boolean {
const approver = this.getUser(approverId);
const hierarchy = this.rbac.getRoleHierarchy();
// Check if approver has sufficient level
const approverMaxLevel = Math.max(
...approver.roles.map(r => hierarchy.getRoleLevel(r))
);
// Update approvers
for (const a of request.approvers) {
if (a.level <= approverMaxLevel && a.status === 'pending') {
a.status = 'approved';
a.timestamp = Date.now();
}
}
// Check if all approvals received
const allApproved = request.approvers.every(a => a.status === 'approved');
if (allApproved) {
request.status = 'approved';
this.executeAction(request);
}
return allApproved;
}
private getRequiredApprovalLevels(action: string): number[] {
// Define approval requirements
const requirements: Record = {
'budget:approve:small': [30], // Manager
'budget:approve:medium': [30, 50], // Manager + Director
'budget:approve:large': [30, 50, 90], // Manager + Director + Executive
'user:delete': [50], // Director
'system:shutdown': [90, 100], // Executive + CEO
};
return requirements[action] || [30];
}
private findUserAtLevel(level: number): string {
// Find user with this role level from database
return `user-level-${level}`;
}
private executeAction(request: ApprovalRequest): void {
console.log(`Executing approved action: ${request.action}`);
}
private getUser(userId: string): RBACUser {
return { id: userId, roles: [] };
}
}
// Usage
const workflow = new ApprovalWorkflow(rbac);
// Engineer requests budget approval
const request = workflow.createRequest(
'eng-1',
'engineer',
'budget:approve:large',
'project-x'
);
console.log('Request created:', request);
// {
// id: 'req-123',
// approvers: [
// { userId: 'user-level-30', level: 30, status: 'pending' },
// { userId: 'user-level-50', level: 50, status: 'pending' },
// { userId: 'user-level-90', level: 90, status: 'pending' }
// ]
// }
// Manager approves (level 30)
workflow.approve(request, 'mgr-1');
// Director approves (level 50)
workflow.approve(request, 'dir-1');
// CEO approves (level 100) - approves both level 90 and 100
const approved = workflow.approve(request, 'ceo-1');
console.log('Fully approved:', approved); // true
```
## Document Access Control
```typescript
interface Document {
id: string;
title: string;
ownerId: string;
ownerRole: string;
classification: 'public' | 'internal' | 'confidential' | 'secret';
content: string;
}
class DocumentAccessControl {
constructor(private rbac: RBAC) {}
canAccessDocument(user: RBACUser, document: Document): boolean {
// Owner can always access
if (user.id === document.ownerId) {
return true;
}
// Check permission based on classification
const classificationPermission = `document:read:${document.classification}`;
if (this.rbac.hasPermission(user, classificationPermission)) {
return true;
}
// Check hierarchy - higher roles can access lower role documents
const hierarchy = this.rbac.getRoleHierarchy();
const ownerLevel = hierarchy.getRoleLevel(document.ownerRole);
for (const userRole of user.roles) {
const userLevel = hierarchy.getRoleLevel(userRole);
if (userLevel > ownerLevel) {
return true;
}
}
return false;
}
canEditDocument(user: RBACUser, document: Document): boolean {
// Owner can edit
if (user.id === document.ownerId) {
return this.rbac.hasPermission(user, 'document:edit:own');
}
// Higher hierarchy can edit
const hierarchy = this.rbac.getRoleHierarchy();
const ownerLevel = hierarchy.getRoleLevel(document.ownerRole);
for (const userRole of user.roles) {
const userLevel = hierarchy.getRoleLevel(userRole);
if (userLevel > ownerLevel) {
return this.rbac.hasPermission(user, 'document:edit:any');
}
}
return false;
}
canDeleteDocument(user: RBACUser, document: Document): boolean {
// Must have delete permission
if (!this.rbac.hasPermission(user, 'document:delete')) {
return false;
}
// Must be significantly higher in hierarchy (2+ levels)
const hierarchy = this.rbac.getRoleHierarchy();
const ownerLevel = hierarchy.getRoleLevel(document.ownerRole);
for (const userRole of user.roles) {
const userLevel = hierarchy.getRoleLevel(userRole);
if (userLevel >= ownerLevel + 20) { // Require 20+ level difference
return true;
}
}
return false;
}
}
// Setup permissions
rbac.createRole('intern', ['document:read:public', 'document:edit:own']);
rbac.createRole('employee', ['document:read:internal', 'document:edit:own']);
rbac.createRole('manager', ['document:read:confidential', 'document:edit:any', 'document:delete']);
rbac.createRole('director', ['document:read:secret', 'document:edit:any', 'document:delete']);
const hierarchy = rbac.getRoleHierarchy();
hierarchy.setRoleLevel('intern', 1);
hierarchy.setRoleLevel('employee', 10);
hierarchy.setRoleLevel('manager', 30);
hierarchy.setRoleLevel('director', 50);
// Usage
const docControl = new DocumentAccessControl(rbac);
const employeeDoc: Document = {
id: 'doc-1',
title: 'Project Plan',
ownerId: 'emp-1',
ownerRole: 'employee',
classification: 'internal',
content: '...'
};
const intern = { id: 'int-1', roles: ['intern'] };
const employee = { id: 'emp-2', roles: ['employee'] };
const manager = { id: 'mgr-1', roles: ['manager'] };
console.log(docControl.canAccessDocument(intern, employeeDoc)); // false (no permission)
console.log(docControl.canAccessDocument(employee, employeeDoc)); // true (same level + permission)
console.log(docControl.canAccessDocument(manager, employeeDoc)); // true (higher level)
console.log(docControl.canEditDocument(employee, employeeDoc)); // false (not owner)
console.log(docControl.canEditDocument(manager, employeeDoc)); // true (higher level + edit:any)
console.log(docControl.canDeleteDocument(manager, employeeDoc)); // false (not 20+ levels higher)
console.log(docControl.canDeleteDocument(manager, internDoc)); // true (29 levels higher)
```
## Next Steps
### Wildcard Permissions Examples
> Source: https://fire-shield.dev/examples/wildcards
# Wildcard Permissions Examples
## Resource-Based Wildcards
```typescript
import { RBAC, RBACBuilder } from '@fire-shield/core';
const rbac = new RBACBuilder()
.useBitSystem()
.enableWildcards()
// User management permissions
.addPermission('user:read')
.addPermission('user:create')
.addPermission('user:update')
.addPermission('user:delete')
// Post management permissions
.addPermission('post:read')
.addPermission('post:create')
.addPermission('post:update')
.addPermission('post:delete')
// Comment management permissions
.addPermission('comment:read')
.addPermission('comment:create')
.addPermission('comment:update')
.addPermission('comment:delete')
// Roles with wildcards
.addRole('admin', ['*']) // Everything
.addRole('moderator', ['post:*', 'comment:*', 'user:read']) // All post/comment actions
.addRole('editor', ['post:*']) // All post actions
.addRole('author', ['post:read', 'post:create', 'post:update']) // Limited post actions
.addRole('viewer', ['post:read', 'comment:read']) // Read-only
.build();
// Usage
const admin = { id: '1', roles: ['admin'] };
const moderator = { id: '2', roles: ['moderator'] };
const editor = { id: '3', roles: ['editor'] };
const author = { id: '4', roles: ['author'] };
const viewer = { id: '5', roles: ['viewer'] };
// Admin has everything
console.log(rbac.hasPermission(admin, 'user:delete')); // true
console.log(rbac.hasPermission(admin, 'system:reboot')); // true (wildcard matches all)
// Moderator can manage posts and comments
console.log(rbac.hasPermission(moderator, 'post:delete')); // true
console.log(rbac.hasPermission(moderator, 'comment:delete')); // true
console.log(rbac.hasPermission(moderator, 'user:delete')); // false
// Editor can only manage posts
console.log(rbac.hasPermission(editor, 'post:delete')); // true
console.log(rbac.hasPermission(editor, 'comment:delete')); // false
// Author has limited post permissions
console.log(rbac.hasPermission(author, 'post:create')); // true
console.log(rbac.hasPermission(author, 'post:delete')); // false
// Viewer can only read
console.log(rbac.hasPermission(viewer, 'post:read')); // true
console.log(rbac.hasPermission(viewer, 'post:write')); // false
```
## Multi-Level Wildcards
```typescript
const rbac = new RBACBuilder()
.enableWildcards()
// System administration
.addPermission('system:server:start')
.addPermission('system:server:stop')
.addPermission('system:server:restart')
.addPermission('system:database:backup')
.addPermission('system:database:restore')
.addPermission('system:logs:read')
.addPermission('system:logs:delete')
// Application management
.addPermission('app:users:create')
.addPermission('app:users:delete')
.addPermission('app:settings:read')
.addPermission('app:settings:write')
// Roles with multi-level wildcards
.addRole('sysadmin', ['system:*']) // All system operations
.addRole('dba', ['system:database:*']) // Only database operations
.addRole('devops', ['system:server:*', 'system:logs:read']) // Server ops + log reading
.addRole('app-admin', ['app:*']) // All app operations
.addRole('user-manager', ['app:users:*']) // Only user management
.build();
// Usage
const sysadmin = { id: '1', roles: ['sysadmin'] };
const dba = { id: '2', roles: ['dba'] };
const devops = { id: '3', roles: ['devops'] };
console.log(rbac.hasPermission(sysadmin, 'system:server:start')); // true
console.log(rbac.hasPermission(sysadmin, 'system:database:backup')); // true
console.log(rbac.hasPermission(dba, 'system:database:backup')); // true
console.log(rbac.hasPermission(dba, 'system:server:start')); // false
console.log(rbac.hasPermission(devops, 'system:server:restart')); // true
console.log(rbac.hasPermission(devops, 'system:database:backup')); // false
```
## Multi-Tenant Wildcards
```typescript
interface Tenant {
id: string;
name: string;
}
interface TenantUser extends RBACUser {
tenantId: string;
}
class MultiTenantRBAC {
private rbac: RBAC;
constructor() {
this.rbac = new RBACBuilder()
.enableWildcards()
// Per-tenant permissions
.addPermission('tenant:*:user:read')
.addPermission('tenant:*:user:write')
.addPermission('tenant:*:data:read')
.addPermission('tenant:*:data:write')
.addPermission('tenant:*:settings:read')
.addPermission('tenant:*:settings:write')
// Platform-wide permissions
.addPermission('platform:tenant:create')
.addPermission('platform:tenant:delete')
.addPermission('platform:analytics:read')
// Roles
.addRole('platform-admin', ['platform:*', 'tenant:*:*:*']) // Full access
.addRole('tenant-admin', []) // Permissions added dynamically per tenant
.addRole('tenant-user', []) // Permissions added dynamically per tenant
.build();
}
// Grant tenant-specific permissions
grantTenantAccess(user: TenantUser, role: string): void {
const tenantId = user.tenantId;
if (role === 'tenant-admin') {
// Admin can do everything in their tenant
if (!user.permissions) user.permissions = [];
user.permissions.push(`tenant:${tenantId}:*:*`);
} else if (role === 'tenant-user') {
// Regular user has limited access
if (!user.permissions) user.permissions = [];
user.permissions.push(`tenant:${tenantId}:data:read`);
user.permissions.push(`tenant:${tenantId}:user:read`);
}
}
canAccessTenantResource(
user: TenantUser,
tenantId: string,
resource: string,
action: string
): boolean {
const permission = `tenant:${tenantId}:${resource}:${action}`;
return this.rbac.hasPermission(user, permission);
}
}
// Usage
const multiTenant = new MultiTenantRBAC();
// Platform admin
const platformAdmin: TenantUser = {
id: 'admin-1',
roles: ['platform-admin'],
tenantId: 'tenant-1'
};
// Tenant admins
const tenant1Admin: TenantUser = {
id: 'user-1',
roles: ['tenant-admin'],
tenantId: 'tenant-1',
permissions: []
};
const tenant2Admin: TenantUser = {
id: 'user-2',
roles: ['tenant-admin'],
tenantId: 'tenant-2',
permissions: []
};
// Grant tenant-specific access
multiTenant.grantTenantAccess(tenant1Admin, 'tenant-admin');
multiTenant.grantTenantAccess(tenant2Admin, 'tenant-admin');
// Platform admin can access any tenant
console.log(multiTenant.canAccessTenantResource(
platformAdmin, 'tenant-1', 'data', 'write'
)); // true
console.log(multiTenant.canAccessTenantResource(
platformAdmin, 'tenant-2', 'data', 'write'
)); // true
// Tenant admin can only access their own tenant
console.log(multiTenant.canAccessTenantResource(
tenant1Admin, 'tenant-1', 'data', 'write'
)); // true
console.log(multiTenant.canAccessTenantResource(
tenant1Admin, 'tenant-2', 'data', 'write'
)); // false
```
## Dynamic Wildcard Permissions
```typescript
class DynamicPermissionBuilder {
private rbac: RBAC;
constructor() {
this.rbac = new RBACBuilder()
.enableWildcards()
.build();
}
// Generate permissions for a new resource type
registerResource(resourceType: string, actions: string[]): void {
for (const action of actions) {
const permission = `${resourceType}:${action}`;
this.rbac.addPermission(permission);
}
}
// Create role with wildcard for resource
createResourceRole(roleName: string, resourceType: string): void {
this.rbac.createRole(roleName, [`${resourceType}:*`]);
}
// Create role with specific actions across resources
createActionRole(roleName: string, action: string, resources: string[]): void {
const permissions = resources.map(r => `${r}:${action}`);
this.rbac.createRole(roleName, permissions);
}
// Create custom role with mixed wildcards
createCustomRole(
roleName: string,
wildcardPatterns: string[],
specificPermissions: string[]
): void {
this.rbac.createRole(roleName, [...wildcardPatterns, ...specificPermissions]);
}
}
// Usage
const builder = new DynamicPermissionBuilder();
// Register different resource types
builder.registerResource('article', ['read', 'create', 'update', 'delete', 'publish']);
builder.registerResource('video', ['read', 'upload', 'edit', 'delete', 'monetize']);
builder.registerResource('podcast', ['read', 'upload', 'edit', 'delete']);
// Create resource-specific roles
builder.createResourceRole('article-manager', 'article'); // Can do anything with articles
builder.createResourceRole('video-manager', 'video'); // Can do anything with videos
// Create action-specific roles
builder.createActionRole('content-reader', 'read', ['article', 'video', 'podcast']);
builder.createActionRole('content-creator', 'create', ['article', 'video', 'podcast']);
// Create custom mixed role
builder.createCustomRole(
'publisher',
['article:*', 'video:*'], // Full access to articles and videos
['podcast:read', 'podcast:upload'] // Limited podcast access
);
// Test permissions
const articleManager = { id: '1', roles: ['article-manager'] };
const contentReader = { id: '2', roles: ['content-reader'] };
const publisher = { id: '3', roles: ['publisher'] };
console.log(builder.rbac.hasPermission(articleManager, 'article:publish')); // true
console.log(builder.rbac.hasPermission(articleManager, 'video:upload')); // false
console.log(builder.rbac.hasPermission(contentReader, 'article:read')); // true
console.log(builder.rbac.hasPermission(contentReader, 'article:delete')); // false
console.log(builder.rbac.hasPermission(publisher, 'article:publish')); // true
console.log(builder.rbac.hasPermission(publisher, 'video:monetize')); // true
console.log(builder.rbac.hasPermission(publisher, 'podcast:delete')); // false
```
## API Endpoint Protection
```typescript
import express from 'express';
import { createExpressRBAC } from '@fire-shield/express';
const rbac = new RBACBuilder()
.enableWildcards()
// API endpoint permissions
.addPermission('api:v1:users:get')
.addPermission('api:v1:users:post')
.addPermission('api:v1:users:put')
.addPermission('api:v1:users:delete')
.addPermission('api:v1:posts:get')
.addPermission('api:v1:posts:post')
.addPermission('api:v1:posts:put')
.addPermission('api:v1:posts:delete')
// Roles
.addRole('api-admin', ['api:*']) // All API access
.addRole('api-user', ['api:v1:*:get']) // Read-only all endpoints
.addRole('user-manager', ['api:v1:users:*']) // Full user management
.addRole('content-editor', ['api:v1:posts:*']) // Full post management
.build();
const app = express();
const rbacMiddleware = createExpressRBAC(rbac, {
getUser: (req) => req.user
});
// Protect endpoints with wildcards
app.get('/api/v1/users',
rbacMiddleware.requirePermission('api:v1:users:get'),
(req, res) => res.json({ users: [] })
);
app.post('/api/v1/users',
rbacMiddleware.requirePermission('api:v1:users:post'),
(req, res) => res.json({ created: true })
);
app.delete('/api/v1/users/:id',
rbacMiddleware.requirePermission('api:v1:users:delete'),
(req, res) => res.json({ deleted: true })
);
// Dynamic permission checking
app.use('/api/v1/:resource/:id?', (req, res, next) => {
const { resource } = req.params;
const method = req.method.toLowerCase();
const permission = `api:v1:${resource}:${method}`;
if (!rbac.hasPermission(req.user, permission)) {
return res.status(403).json({ error: 'Forbidden' });
}
next();
});
```
## Feature Flag System
```typescript
class FeatureFlagSystem {
private rbac: RBAC;
constructor() {
this.rbac = new RBACBuilder()
.enableWildcards()
// Feature permissions
.addPermission('feature:beta:*')
.addPermission('feature:premium:*')
.addPermission('feature:experimental:*')
// Specific features
.addPermission('feature:beta:new-editor')
.addPermission('feature:beta:advanced-search')
.addPermission('feature:premium:analytics')
.addPermission('feature:premium:api-access')
.addPermission('feature:experimental:ai-assistant')
// Roles
.addRole('beta-tester', ['feature:beta:*'])
.addRole('premium-user', ['feature:premium:*'])
.addRole('internal-user', ['feature:*']) // All features
.build();
}
hasFeature(user: RBACUser, featureName: string): boolean {
return this.rbac.hasPermission(user, `feature:${featureName}`);
}
enableFeatureForUser(user: RBACUser, featureName: string): void {
if (!user.permissions) user.permissions = [];
user.permissions.push(`feature:${featureName}`);
}
getAvailableFeatures(user: RBACUser): string[] {
const allFeatures = [
'beta:new-editor',
'beta:advanced-search',
'premium:analytics',
'premium:api-access',
'experimental:ai-assistant'
];
return allFeatures.filter(feature => this.hasFeature(user, feature));
}
}
// Usage
const featureFlags = new FeatureFlagSystem();
const betaUser = { id: '1', roles: ['beta-tester'] };
const premiumUser = { id: '2', roles: ['premium-user'] };
const internalUser = { id: '3', roles: ['internal-user'] };
console.log(featureFlags.hasFeature(betaUser, 'beta:new-editor')); // true
console.log(featureFlags.hasFeature(betaUser, 'premium:analytics')); // false
console.log(featureFlags.hasFeature(premiumUser, 'premium:analytics')); // true
console.log(featureFlags.hasFeature(premiumUser, 'beta:new-editor')); // false
console.log(featureFlags.hasFeature(internalUser, 'experimental:ai-assistant')); // true
console.log(featureFlags.getAvailableFeatures(betaUser));
// ['beta:new-editor', 'beta:advanced-search']
```
## Next Steps
### Audit Logging Examples
> Source: https://fire-shield.dev/examples/audit-logging
# Audit Logging Examples
## Basic Audit Logging
```typescript
import { RBAC, ConsoleAuditLogger } from '@fire-shield/core';
// Create RBAC with console logger
const rbac = new RBAC({
auditLogger: new ConsoleAuditLogger()
});
rbac.createRole('admin', ['users:*']);
rbac.createRole('viewer', ['users:read']);
const admin = { id: 'admin-1', roles: ['admin'] };
const viewer = { id: 'viewer-1', roles: ['viewer'] };
// All permission checks are logged
rbac.hasPermission(admin, 'users:delete');
// Console output:
// [AUDIT] permission_check | user: admin-1 | permission: users:delete | allowed: true
rbac.hasPermission(viewer, 'users:delete');
// Console output:
// [AUDIT] permission_check | user: viewer-1 | permission: users:delete | allowed: false | reason: User lacks permission: users:delete
```
## Database Audit Logging
```typescript
import { RBAC, BufferedAuditLogger, AuditEvent } from '@fire-shield/core';
import { db } from './database'; // Your database client
// Create buffered logger that writes to database
const auditLogger = new BufferedAuditLogger(
async (events: AuditEvent[]) => {
// Batch insert audit events
await db.auditLogs.insertMany(
events.map(event => ({
type: event.type,
userId: event.userId,
permission: event.permission,
allowed: event.allowed,
reason: event.reason,
context: event.context,
timestamp: new Date(event.timestamp),
createdAt: new Date()
}))
);
},
{
maxBufferSize: 100, // Flush when buffer reaches 100 events
flushIntervalMs: 5000 // Or every 5 seconds
}
);
const rbac = new RBAC({ auditLogger });
// Events are buffered and batch-written to database
rbac.hasPermission(user, 'post:delete');
rbac.hasPermission(user, 'user:create');
// ... more checks
// Manual flush if needed
await auditLogger.flush();
```
## Security Monitoring System
```typescript
import { AuditLogger, AuditEvent } from '@fire-shield/core';
class SecurityMonitorLogger implements AuditLogger {
private failedAttempts = new Map<string, number>();
private suspiciousActivity = new Map<string, AuditEvent[]>();
log(event: AuditEvent): void {
// Track failed authorization attempts
if (!event.allowed) {
this.trackFailedAttempt(event);
}
// Detect suspicious patterns
this.detectSuspiciousActivity(event);
// Log high-privilege access
if (this.isHighPrivilegeAccess(event)) {
this.alertSecurityTeam(event);
}
}
private trackFailedAttempt(event: AuditEvent): void {
const userId = event.userId;
const count = (this.failedAttempts.get(userId) || 0) + 1;
this.failedAttempts.set(userId, count);
// Alert after 5 failed attempts
if (count >= 5) {
console.error(`🚨 SECURITY ALERT: User ${userId} has ${count} failed authorization attempts`);
this.lockUser(userId);
}
// Reset counter after 1 hour
setTimeout(() => {
this.failedAttempts.set(userId, 0);
}, 3600000);
}
private detectSuspiciousActivity(event: AuditEvent): void {
const userId = event.userId;
const recentEvents = this.suspiciousActivity.get(userId) || [];
recentEvents.push(event);
// Keep only last 10 minutes of activity
const tenMinutesAgo = Date.now() - 600000;
const filtered = recentEvents.filter(e => e.timestamp > tenMinutesAgo);
this.suspiciousActivity.set(userId, filtered);
// Alert on unusual patterns
if (this.hasUnusualPattern(filtered)) {
console.warn(`⚠️ Suspicious activity detected for user ${userId}`);
this.notifySecurityTeam(userId, filtered);
}
}
private hasUnusualPattern(events: AuditEvent[]): boolean {
// More than 50 requests in 10 minutes
if (events.length > 50) return true;
// Multiple failed high-privilege attempts
const failedHighPriv = events.filter(
e => !e.allowed && this.isHighPrivilegeAccess(e)
);
if (failedHighPriv.length > 3) return true;
// Accessing many different resources rapidly
const uniquePermissions = new Set(events.map(e => e.permission));
if (uniquePermissions.size > 20) return true;
return false;
}
private isHighPrivilegeAccess(event: AuditEvent): boolean {
const highPrivPermissions = [
'admin:*',
'system:*',
'user:delete',
'database:*'
];
return highPrivPermissions.some(pattern =>
event.permission.includes(pattern.replace('*', ''))
);
}
private alertSecurityTeam(event: AuditEvent): void {
console.log(`🔐 High-privilege access: ${event.userId} → ${event.permission}`);
// Send to monitoring service (Datadog, New Relic, etc.)
}
private lockUser(userId: string): void {
console.log(`🔒 Locking user ${userId} due to failed attempts`);
// Implement user locking logic
}
private notifySecurityTeam(userId: string, events: AuditEvent[]): void {
console.log(`📧 Notifying security team about user ${userId}`);
// Send email/Slack notification
}
}
// Usage
const rbac = new RBAC({
auditLogger: new SecurityMonitorLogger()
});
```
## Compliance Audit System
```typescript
import { AuditLogger, AuditEvent } from '@fire-shield/core';
interface ComplianceAuditLog extends AuditEvent {
// Additional compliance fields
ipAddress?: string;
userAgent?: string;
sessionId?: string;
dataClassification?: 'public' | 'internal' | 'confidential' | 'restricted';
retentionDays?: number;
}
class ComplianceAuditLogger implements AuditLogger {
private retentionPolicies = new Map<string, number>([
['public', 30],
['internal', 90],
['confidential', 365],
['restricted', 2555] // 7 years
]);
async log(event: AuditEvent): Promise<void> {
const complianceLog: ComplianceAuditLog = {
...event,
ipAddress: event.context?.ip,
userAgent: event.context?.userAgent,
sessionId: event.context?.sessionId,
dataClassification: this.classifyData(event.permission),
retentionDays: this.getRetentionPeriod(event.permission)
};
// Write to compliance database
await this.writeToComplianceLog(complianceLog);
// Check if requires immediate reporting
if (this.requiresImmediateReporting(complianceLog)) {
await this.reportToComplianceOfficer(complianceLog);
}
}
private classifyData(permission: string): string {
if (permission.includes('pii') || permission.includes('sensitive')) {
return 'restricted';
}
if (permission.includes('financial') || permission.includes('health')) {
return 'confidential';
}
if (permission.includes('internal')) {
return 'internal';
}
return 'public';
}
private getRetentionPeriod(permission: string): number {
const classification = this.classifyData(permission);
return this.retentionPolicies.get(classification) || 30;
}
private requiresImmediateReporting(log: ComplianceAuditLog): boolean {
// Report access to restricted data
if (log.dataClassification === 'restricted') {
return true;
}
// Report failed high-privilege attempts
if (!log.allowed && log.permission.includes('admin')) {
return true;
}
return false;
}
private async writeToComplianceLog(log: ComplianceAuditLog): Promise<void> {
// Write to secure, immutable storage
await db.complianceLogs.insert({
...log,
hash: this.calculateHash(log), // Tamper detection
encrypted: this.encrypt(log), // Encryption for sensitive data
expiresAt: new Date(Date.now() + log.retentionDays! * 86400000)
});
}
private async reportToComplianceOfficer(log: ComplianceAuditLog): Promise<void> {
// Send notification
await emailService.send({
to: 'compliance@company.com',
subject: `Compliance Alert: ${log.dataClassification} data access`,
body: `
User: ${log.userId}
Permission: ${log.permission}
Allowed: ${log.allowed}
IP: ${log.ipAddress}
Time: ${new Date(log.timestamp).toISOString()}
`
});
}
private calculateHash(log: ComplianceAuditLog): string {
// Calculate hash for tamper detection
return crypto
.createHash('sha256')
.update(JSON.stringify(log))
.digest('hex');
}
private encrypt(log: ComplianceAuditLog): string {
// Encrypt sensitive fields
return encryptionService.encrypt(JSON.stringify(log));
}
}
// Usage
const rbac = new RBAC({
auditLogger: new ComplianceAuditLogger()
});
```
## Multi-Channel Audit Logging
```typescript
import { MultiAuditLogger, ConsoleAuditLogger, BufferedAuditLogger } from '@fire-shield/core';
// Log to console
const consoleLogger = new ConsoleAuditLogger();
// Log to database
const dbLogger = new BufferedAuditLogger(
async (events) => await db.auditLogs.insertMany(events),
{ maxBufferSize: 50, flushIntervalMs: 3000 }
);
// Log to external monitoring service
const monitoringLogger = new BufferedAuditLogger(
async (events) => {
await fetch('https://monitoring.example.com/audit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(events)
});
},
{ maxBufferSize: 100, flushIntervalMs: 10000 }
);
// Log to Slack for critical events
class SlackAuditLogger implements AuditLogger {
async log(event: AuditEvent): Promise<void> {
// Only log critical events to Slack
if (this.isCritical(event)) {
await fetch(process.env.SLACK_WEBHOOK_URL!, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
text: `🔐 Critical Access: ${event.userId} → ${event.permission}`,
attachments: [{
color: event.allowed ? 'good' : 'danger',
fields: [
{ title: 'User', value: event.userId, short: true },
{ title: 'Permission', value: event.permission, short: true },
{ title: 'Allowed', value: event.allowed.toString(), short: true },
{ title: 'Reason', value: event.reason || 'N/A', short: true }
]
}]
})
});
}
}
private isCritical(event: AuditEvent): boolean {
return event.permission.includes('admin') ||
event.permission.includes('delete') ||
event.permission.includes('system');
}
}
// Combine all loggers
const multiLogger = new MultiAuditLogger([
consoleLogger,
dbLogger,
monitoringLogger,
new SlackAuditLogger()
]);
const rbac = new RBAC({ auditLogger: multiLogger });
```
## Query and Analysis
```typescript
class AuditLogAnalyzer {
async getUserActivity(userId: string, days: number = 7): Promise<AuditEvent[]> {
const since = Date.now() - (days * 86400000);
return await db.auditLogs.find({
userId,
timestamp: { $gte: since }
}).toArray();
}
async getFailedAttempts(hours: number = 24): Promise<AuditEvent[]> {
const since = Date.now() - (hours * 3600000);
return await db.auditLogs.find({
allowed: false,
timestamp: { $gte: since }
}).toArray();
}
async getPermissionUsage(permission: string): Promise<{
total: number;
allowed: number;
denied: number;
uniqueUsers: number;
}> {
const logs = await db.auditLogs.find({ permission }).toArray();
return {
total: logs.length,
allowed: logs.filter(l => l.allowed).length,
denied: logs.filter(l => !l.allowed).length,
uniqueUsers: new Set(logs.map(l => l.userId)).size
};
}
async getSecurityReport(days: number = 30): Promise<{
totalChecks: number;
failedChecks: number;
suspiciousUsers: string[];
topPermissions: Array<{ permission: string; count: number }>;
}> {
const since = Date.now() - (days * 86400000);
const logs = await db.auditLogs.find({
timestamp: { $gte: since }
}).toArray();
// Find users with high failure rate
const userFailures = new Map<string, number>();
logs.forEach(log => {
if (!log.allowed) {
userFailures.set(log.userId, (userFailures.get(log.userId) || 0) + 1);
}
});
const suspiciousUsers = Array.from(userFailures.entries())
.filter(([_, count]) => count > 10)
.map(([userId]) => userId);
// Count permission usage
const permissionCounts = new Map<string, number>();
logs.forEach(log => {
permissionCounts.set(
log.permission,
(permissionCounts.get(log.permission) || 0) + 1
);
});
const topPermissions = Array.from(permissionCounts.entries())
.map(([permission, count]) => ({ permission, count }))
.sort((a, b) => b.count - a.count)
.slice(0, 10);
return {
totalChecks: logs.length,
failedChecks: logs.filter(l => !l.allowed).length,
suspiciousUsers,
topPermissions
};
}
async exportAuditLogs(
startDate: Date,
endDate: Date,
format: 'json' | 'csv'
): Promise<string> {
const logs = await db.auditLogs.find({
timestamp: {
$gte: startDate.getTime(),
$lte: endDate.getTime()
}
}).toArray();
if (format === 'csv') {
return this.convertToCSV(logs);
}
return JSON.stringify(logs, null, 2);
}
private convertToCSV(logs: AuditEvent[]): string {
const headers = ['Timestamp', 'Type', 'User ID', 'Permission', 'Allowed', 'Reason'];
const rows = logs.map(log => [
new Date(log.timestamp).toISOString(),
log.type,
log.userId,
log.permission,
log.allowed.toString(),
log.reason || ''
]);
return [headers, ...rows].map(row => row.join(',')).join('\n');
}
}
// Usage
const analyzer = new AuditLogAnalyzer();
// Get user activity
const userActivity = await analyzer.getUserActivity('user-123', 7);
console.log(`User had ${userActivity.length} permission checks in last 7 days`);
// Get security report
const report = await analyzer.getSecurityReport(30);
console.log('Security Report:', report);
// Export logs for compliance
const csvData = await analyzer.exportAuditLogs(
new Date('2025-01-01'),
new Date('2025-01-31'),
'csv'
);
```
## Real-time Audit Dashboard
```typescript
import { EventEmitter } from 'events';
class RealtimeAuditLogger extends EventEmitter implements AuditLogger {
log(event: AuditEvent): void {
// Emit event for real-time processing
this.emit('audit', event);
// Also persist to database
db.auditLogs.insert(event);
}
}
// Setup real-time monitoring
const realtimeLogger = new RealtimeAuditLogger();
// Listen for audit events
realtimeLogger.on('audit', (event: AuditEvent) => {
// Send to WebSocket clients
wsServer.broadcast({
type: 'audit_event',
data: event
});
// Update real-time metrics
metrics.increment('permission_checks');
if (!event.allowed) {
metrics.increment('permission_denials');
}
});
const rbac = new RBAC({ auditLogger: realtimeLogger });
```
## Next Steps
### Multi-Tenancy Examples
> Source: https://fire-shield.dev/examples/multi-tenancy
# Multi-Tenancy Examples
## Basic Multi-Tenant Setup
```typescript
import { RBAC, RBACBuilder } from '@fire-shield/core';
interface TenantUser extends RBACUser {
tenantId: string;
}
class MultiTenantRBAC {
private rbac: RBAC;
constructor() {
this.rbac = new RBACBuilder()
.enableWildcards()
// Platform-level permissions
.addPermission('platform:tenant:create')
.addPermission('platform:tenant:delete')
.addPermission('platform:tenant:list')
.addPermission('platform:analytics:view')
// Tenant-level permissions (use with tenant ID)
.addPermission('tenant:user:create')
.addPermission('tenant:user:delete')
.addPermission('tenant:data:read')
.addPermission('tenant:data:write')
.addPermission('tenant:settings:manage')
// Platform roles
.addRole('platform-admin', ['platform:*'])
// Tenant roles (permissions granted dynamically)
.addRole('tenant-owner', [])
.addRole('tenant-admin', [])
.addRole('tenant-member', [])
.build();
}
// Check if user can access tenant
canAccessTenant(user: TenantUser, tenantId: string): boolean {
// Platform admins can access any tenant
if (user.roles.includes('platform-admin')) {
return true;
}
// User must belong to the tenant
return user.tenantId === tenantId;
}
// Check tenant-scoped permission
hasPermissionInTenant(
user: TenantUser,
tenantId: string,
permission: string
): boolean {
// Check tenant access first
if (!this.canAccessTenant(user, tenantId)) {
return false;
}
// For platform admins, grant all tenant permissions
if (user.roles.includes('platform-admin')) {
return true;
}
// Check user's permissions
return this.rbac.hasPermission(user, permission);
}
// Grant tenant-specific role permissions
grantTenantRole(user: TenantUser, role: 'owner' | 'admin' | 'member'): void {
if (!user.permissions) user.permissions = [];
if (role === 'owner') {
user.permissions.push('tenant:*');
} else if (role === 'admin') {
user.permissions.push('tenant:user:*');
user.permissions.push('tenant:data:*');
user.permissions.push('tenant:settings:*');
} else if (role === 'member') {
user.permissions.push('tenant:data:read');
user.permissions.push('tenant:data:write');
}
}
}
// Usage
const multiTenant = new MultiTenantRBAC();
// Platform admin
const platformAdmin: TenantUser = {
id: 'admin-1',
roles: ['platform-admin'],
tenantId: 'platform'
};
// Tenant users
const tenantOwner: TenantUser = {
id: 'owner-1',
roles: ['tenant-owner'],
tenantId: 'tenant-abc',
permissions: []
};
const tenantMember: TenantUser = {
id: 'member-1',
roles: ['tenant-member'],
tenantId: 'tenant-abc',
permissions: []
};
// Grant permissions based on roles
multiTenant.grantTenantRole(tenantOwner, 'owner');
multiTenant.grantTenantRole(tenantMember, 'member');
// Platform admin can access any tenant
console.log(multiTenant.canAccessTenant(platformAdmin, 'tenant-abc')); // true
console.log(multiTenant.canAccessTenant(platformAdmin, 'tenant-xyz')); // true
// Tenant users can only access their tenant
console.log(multiTenant.canAccessTenant(tenantOwner, 'tenant-abc')); // true
console.log(multiTenant.canAccessTenant(tenantOwner, 'tenant-xyz')); // false
// Permission checks
console.log(multiTenant.hasPermissionInTenant(
tenantOwner, 'tenant-abc', 'tenant:user:delete'
)); // true
console.log(multiTenant.hasPermissionInTenant(
tenantMember, 'tenant-abc', 'tenant:user:delete'
)); // false
```
## Hierarchical Multi-Tenancy
```typescript
interface Tenant {
id: string;
name: string;
parentId?: string;
level: number; // 0 = root, 1 = organization, 2 = department, etc.
}
class HierarchicalMultiTenancy {
private rbac: RBAC;
private tenants = new Map<string, Tenant>();
constructor() {
this.rbac = new RBACBuilder()
.enableWildcards()
.build();
}
// Register tenant
registerTenant(tenant: Tenant): void {
this.tenants.set(tenant.id, tenant);
}
// Get all ancestor tenants
getAncestorTenants(tenantId: string): Tenant[] {
const ancestors: Tenant[] = [];
let current = this.tenants.get(tenantId);
while (current?.parentId) {
current = this.tenants.get(current.parentId);
if (current) ancestors.push(current);
}
return ancestors;
}
// Get all descendant tenants
getDescendantTenants(tenantId: string): Tenant[] {
const descendants: Tenant[] = [];
for (const tenant of this.tenants.values()) {
if (this.isDescendant(tenant.id, tenantId)) {
descendants.push(tenant);
}
}
return descendants;
}
private isDescendant(tenantId: string, ancestorId: string): boolean {
const ancestors = this.getAncestorTenants(tenantId);
return ancestors.some(t => t.id === ancestorId);
}
// Check if user can access tenant (including parent access)
canAccessTenant(user: TenantUser, targetTenantId: string): boolean {
// User's own tenant
if (user.tenantId === targetTenantId) {
return true;
}
// Check if user's tenant is an ancestor (parent access)
const isAncestor = this.isDescendant(targetTenantId, user.tenantId);
if (isAncestor && this.rbac.hasPermission(user, 'tenant:inherit:access')) {
return true;
}
return false;
}
// Get all accessible tenants for user
getAccessibleTenants(user: TenantUser): Tenant[] {
const accessible: Tenant[] = [];
for (const tenant of this.tenants.values()) {
if (this.canAccessTenant(user, tenant.id)) {
accessible.push(tenant);
}
}
return accessible;
}
}
// Usage
const hierarchy = new HierarchicalMultiTenancy();
// Register tenant hierarchy
// Root: ACME Corp
// - Sales Dept
// - North Region
// - South Region
// - Engineering Dept
hierarchy.registerTenant({
id: 'acme',
name: 'ACME Corp',
level: 0
});
hierarchy.registerTenant({
id: 'sales',
name: 'Sales Department',
parentId: 'acme',
level: 1
});
hierarchy.registerTenant({
id: 'north-sales',
name: 'North Region Sales',
parentId: 'sales',
level: 2
});
hierarchy.registerTenant({
id: 'engineering',
name: 'Engineering Department',
parentId: 'acme',
level: 1
});
// User at Sales level with inherit permission
const salesManager: TenantUser = {
id: 'mgr-1',
roles: ['tenant-admin'],
tenantId: 'sales',
permissions: ['tenant:inherit:access']
};
// Can access own tenant
console.log(hierarchy.canAccessTenant(salesManager, 'sales')); // true
// Can access child tenant (North Region)
console.log(hierarchy.canAccessTenant(salesManager, 'north-sales')); // true
// Cannot access sibling tenant
console.log(hierarchy.canAccessTenant(salesManager, 'engineering')); // false
// Get all accessible tenants
const accessible = hierarchy.getAccessibleTenants(salesManager);
console.log(accessible.map(t => t.name));
// ['Sales Department', 'North Region Sales']
```
## Resource Isolation
```typescript
interface TenantResource {
id: string;
tenantId: string;
type: string;
data: any;
}
class TenantResourceManager {
private rbac: RBAC;
private resources = new Map<string, TenantResource>();
constructor(rbac: RBAC) {
this.rbac = rbac;
}
// Create resource (must belong to user's tenant)
createResource(
user: TenantUser,
type: string,
data: any
): TenantResource | null {
if (!this.rbac.hasPermission(user, `${type}:create`)) {
return null;
}
const resource: TenantResource = {
id: `${type}-${Date.now()}`,
tenantId: user.tenantId,
type,
data
};
this.resources.set(resource.id, resource);
return resource;
}
// Read resource (with tenant check)
readResource(
user: TenantUser,
resourceId: string
): TenantResource | null {
const resource = this.resources.get(resourceId);
if (!resource) {
return null;
}
// Verify tenant isolation
if (resource.tenantId !== user.tenantId) {
console.error('Tenant isolation violation attempted');
return null;
}
if (!this.rbac.hasPermission(user, `${resource.type}:read`)) {
return null;
}
return resource;
}
// Update resource
updateResource(
user: TenantUser,
resourceId: string,
data: any
): boolean {
const resource = this.resources.get(resourceId);
if (!resource || resource.tenantId !== user.tenantId) {
return false;
}
if (!this.rbac.hasPermission(user, `${resource.type}:update`)) {
return false;
}
resource.data = data;
return true;
}
// List resources (only from user's tenant)
listResources(user: TenantUser, type?: string): TenantResource[] {
const userResources: TenantResource[] = [];
for (const resource of this.resources.values()) {
// Tenant isolation
if (resource.tenantId !== user.tenantId) {
continue;
}
// Type filter
if (type && resource.type !== type) {
continue;
}
// Permission check
if (this.rbac.hasPermission(user, `${resource.type}:read`)) {
userResources.push(resource);
}
}
return userResources;
}
// Delete resource
deleteResource(user: TenantUser, resourceId: string): boolean {
const resource = this.resources.get(resourceId);
if (!resource || resource.tenantId !== user.tenantId) {
return false;
}
if (!this.rbac.hasPermission(user, `${resource.type}:delete`)) {
return false;
}
this.resources.delete(resourceId);
return true;
}
}
// Usage
const rbac = new RBAC();
rbac.createRole('member', ['document:read', 'document:create', 'document:update']);
rbac.createRole('admin', ['document:*']);
const resourceManager = new TenantResourceManager(rbac);
const tenant1User: TenantUser = {
id: 'user-1',
roles: ['member'],
tenantId: 'tenant-1'
};
const tenant2User: TenantUser = {
id: 'user-2',
roles: ['member'],
tenantId: 'tenant-2'
};
// Create resources
const doc1 = resourceManager.createResource(tenant1User, 'document', {
title: 'Tenant 1 Document'
});
const doc2 = resourceManager.createResource(tenant2User, 'document', {
title: 'Tenant 2 Document'
});
// Tenant isolation enforced
console.log(resourceManager.readResource(tenant1User, doc1!.id)); // ✅ Success
console.log(resourceManager.readResource(tenant1User, doc2!.id)); // ❌ null (different tenant)
// List only shows user's tenant resources
console.log(resourceManager.listResources(tenant1User).length); // 1
console.log(resourceManager.listResources(tenant2User).length); // 1
```
## Cross-Tenant Data Sharing
```typescript
interface SharedResource {
resourceId: string;
ownerTenantId: string;
sharedWith: Array<{
tenantId: string;
permissions: string[];
expiresAt?: number;
}>;
}
class CrossTenantSharing {
private rbac: RBAC;
private sharedResources = new Map<string, SharedResource>();
constructor(rbac: RBAC) {
this.rbac = rbac;
}
// Share resource with another tenant
shareResource(
owner: TenantUser,
resourceId: string,
targetTenantId: string,
permissions: string[],
expiresInMs?: number
): boolean {
// Owner must have sharing permission
if (!this.rbac.hasPermission(owner, 'resource:share')) {
return false;
}
const shared: SharedResource = {
resourceId,
ownerTenantId: owner.tenantId,
sharedWith: [{
tenantId: targetTenantId,
permissions,
expiresAt: expiresInMs ? Date.now() + expiresInMs : undefined
}]
};
this.sharedResources.set(resourceId, shared);
return true;
}
// Check if user can access shared resource
canAccessSharedResource(
user: TenantUser,
resourceId: string,
permission: string
): boolean {
const shared = this.sharedResources.get(resourceId);
if (!shared) {
return false;
}
// Owner always has access
if (user.tenantId === shared.ownerTenantId) {
return this.rbac.hasPermission(user, permission);
}
// Check if resource is shared with user's tenant
const share = shared.sharedWith.find(s => s.tenantId === user.tenantId);
if (!share) {
return false;
}
// Check expiration
if (share.expiresAt && Date.now() > share.expiresAt) {
return false;
}
// Check if permission is granted
return share.permissions.includes(permission) ||
share.permissions.includes('*');
}
// Revoke sharing
revokeSharing(
owner: TenantUser,
resourceId: string,
targetTenantId: string
): boolean {
const shared = this.sharedResources.get(resourceId);
if (!shared || shared.ownerTenantId !== owner.tenantId) {
return false;
}
shared.sharedWith = shared.sharedWith.filter(
s => s.tenantId !== targetTenantId
);
return true;
}
}
// Usage
const sharing = new CrossTenantSharing(rbac);
const tenant1Owner: TenantUser = {
id: 'owner-1',
roles: ['tenant-owner'],
tenantId: 'tenant-1',
permissions: ['resource:share']
};
const tenant2User: TenantUser = {
id: 'user-2',
roles: ['tenant-member'],
tenantId: 'tenant-2'
};
// Share resource with another tenant for 1 hour
sharing.shareResource(
tenant1Owner,
'doc-123',
'tenant-2',
['read', 'comment'],
3600000 // 1 hour
);
// Tenant 2 user can now access the shared resource
console.log(sharing.canAccessSharedResource(
tenant2User,
'doc-123',
'read'
)); // true
console.log(sharing.canAccessSharedResource(
tenant2User,
'doc-123',
'delete'
)); // false (not granted)
// Owner can revoke sharing
sharing.revokeSharing(tenant1Owner, 'doc-123', 'tenant-2');
console.log(sharing.canAccessSharedResource(
tenant2User,
'doc-123',
'read'
)); // false (revoked)
```
## Tenant-Specific Feature Flags
```typescript
interface TenantFeatures {
tenantId: string;
plan: 'free' | 'pro' | 'enterprise';
enabledFeatures: string[];
limits: {
maxUsers: number;
maxStorage: number;
maxApiCalls: number;
};
}
class TenantFeatureManager {
private tenantFeatures = new Map<string, TenantFeatures>();
// Feature matrix by plan
private planFeatures = {
free: ['basic:*', 'export:csv'],
pro: ['basic:*', 'advanced:*', 'export:*', 'api:basic'],
enterprise: ['*'] // All features
};
private planLimits = {
free: { maxUsers: 5, maxStorage: 1024, maxApiCalls: 100 },
pro: { maxUsers: 50, maxStorage: 10240, maxApiCalls: 10000 },
enterprise: { maxUsers: -1, maxStorage: -1, maxApiCalls: -1 } // Unlimited
};
registerTenant(tenantId: string, plan: 'free' | 'pro' | 'enterprise'): void {
this.tenantFeatures.set(tenantId, {
tenantId,
plan,
enabledFeatures: this.planFeatures[plan],
limits: this.planLimits[plan]
});
}
hasFeature(tenantId: string, feature: string): boolean {
const tenant = this.tenantFeatures.get(tenantId);
if (!tenant) {
return false;
}
return tenant.enabledFeatures.some(f =>
f === feature || (f.endsWith('*') && feature.startsWith(f.slice(0, -1)))
);
}
checkLimit(tenantId: string, limitType: keyof TenantFeatures['limits'], current: number): boolean {
const tenant = this.tenantFeatures.get(tenantId);
if (!tenant) {
return false;
}
const limit = tenant.limits[limitType];
// -1 means unlimited
if (limit === -1) {
return true;
}
return current < limit;
}
upgradeTenant(tenantId: string, newPlan: 'free' | 'pro' | 'enterprise'): void {
const tenant = this.tenantFeatures.get(tenantId);
if (tenant) {
tenant.plan = newPlan;
tenant.enabledFeatures = this.planFeatures[newPlan];
tenant.limits = this.planLimits[newPlan];
}
}
}
// Usage
const featureManager = new TenantFeatureManager();
featureManager.registerTenant('tenant-free', 'free');
featureManager.registerTenant('tenant-pro', 'pro');
featureManager.registerTenant('tenant-ent', 'enterprise');
// Feature checks
console.log(featureManager.hasFeature('tenant-free', 'basic:reports')); // true
console.log(featureManager.hasFeature('tenant-free', 'advanced:analytics')); // false
console.log(featureManager.hasFeature('tenant-pro', 'advanced:analytics')); // true
console.log(featureManager.hasFeature('tenant-pro', 'api:basic')); // true
console.log(featureManager.hasFeature('tenant-ent', 'any:feature')); // true (has *)
// Limit checks
console.log(featureManager.checkLimit('tenant-free', 'maxUsers', 3)); // true (3 < 5)
console.log(featureManager.checkLimit('tenant-free', 'maxUsers', 10)); // false (10 >= 5)
console.log(featureManager.checkLimit('tenant-ent', 'maxUsers', 1000000)); // true (unlimited)
```
## Next Steps
### Best Practices
> Source: https://fire-shield.dev/examples/best-practices
# Best Practices
## Permission Design
### Use Consistent Naming Conventions
```typescript
// ✅ Good: Clear, consistent pattern
const permissions = [
'user:read',
'user:create',
'user:update',
'user:delete',
'post:read',
'post:create',
'post:update',
'post:delete'
];
// ❌ Bad: Inconsistent naming
const permissions = [
'readUser',
'user-create',
'update_user',
'DeleteUser'
];
```
### Follow Resource:Action Pattern
```typescript
// ✅ Good: Resource:Action format
.addPermission('document:read')
.addPermission('document:write')
.addPermission('invoice:approve')
.addPermission('report:generate')
// ❌ Bad: Unclear structure
.addPermission('read')
.addPermission('write_document')
.addPermission('approveInvoice')
```
### Use Hierarchical Permissions
```typescript
// ✅ Good: Hierarchical structure
const rbac = new RBACBuilder()
.addPermission('api:users:read')
.addPermission('api:users:write')
.addPermission('api:posts:read')
.addPermission('api:posts:write')
.addPermission('api:admin:users:delete')
.build();
// Allows wildcard patterns
// 'api:*' → All API access
// 'api:users:*' → All user operations
// 'api:*:read' → All read operations
```
### Design for Least Privilege
```typescript
// ✅ Good: Specific permissions
.addRole('viewer', ['posts:read', 'comments:read'])
.addRole('editor', ['posts:read', 'posts:write', 'comments:read'])
.addRole('admin', ['posts:*', 'comments:*', 'users:read'])
// ❌ Bad: Overly broad permissions
.addRole('viewer', ['*']) // Too much access for a viewer
.addRole('editor', ['posts:*', 'users:*', 'system:*']) // Unnecessary permissions
```
## Role Design
### Keep Roles Simple and Focused
```typescript
// ✅ Good: Clear, single-purpose roles
.addRole('content-viewer', ['posts:read', 'comments:read'])
.addRole('content-editor', ['posts:read', 'posts:write'])
.addRole('content-publisher', ['posts:read', 'posts:write', 'posts:publish'])
.addRole('user-manager', ['users:read', 'users:create', 'users:update'])
// ❌ Bad: Kitchen sink roles
.addRole('super-user', [
'posts:*', 'comments:*', 'users:*', 'settings:*',
'billing:*', 'analytics:*', 'reports:*'
]) // Too many responsibilities
```
### Use Role Composition
```typescript
// ✅ Good: Compose multiple roles
const user = {
id: 'user-1',
roles: ['content-editor', 'comment-moderator']
};
// User gets combined permissions from both roles
// ❌ Bad: Creating duplicate mega-roles
.addRole('editor-and-moderator', [
'posts:read', 'posts:write',
'comments:read', 'comments:delete', 'comments:moderate'
]) // Harder to maintain
```
### Leverage Role Hierarchy
```typescript
// ✅ Good: Use hierarchy levels
const rbac = new RBACBuilder()
.addRole('intern', ['docs:read'], { level: 1 })
.addRole('junior', ['docs:read', 'docs:write'], { level: 5 })
.addRole('senior', ['docs:*', 'review:*'], { level: 10 })
.addRole('lead', ['docs:*', 'review:*', 'approve:*'], { level: 15 })
.addRole('manager', ['*'], { level: 20 })
.build();
// Allows automatic inheritance and delegation checks
console.log(rbac.canActAsRole('manager', 'senior')); // true
```
## Performance Optimization
### Use Bit-Based System for High Performance
```typescript
// ✅ Good: Bit-based for production
const rbac = new RBACBuilder()
.useBitSystem() // O(1) permission checks
.addPermission('user:read', 1)
.addPermission('user:write', 2)
.addPermission('post:read', 4)
.addPermission('post:write', 8)
.build();
// Ultra-fast checks using bitwise operations
rbac.hasPermission(user, 'user:read'); // ~0.0001ms
// ❌ Avoid: String-based in high-traffic apps
const rbac = new RBAC(); // 10x slower for permission checks
```
### Cache User Permissions
```typescript
// ✅ Good: Cache computed permissions
class PermissionCache {
private cache = new Map<string, Set<string>>();
private ttl = 300000; // 5 minutes
getUserPermissions(rbac: RBAC, user: RBACUser): Set<string> {
const cacheKey = `${user.id}:${user.roles.join(',')}`;
const cached = this.cache.get(cacheKey);
if (cached) {
return cached;
}
// Compute all permissions for user
const permissions = new Set<string>();
for (const role of user.roles) {
const rolePerms = rbac.getRole(role)?.permissions || [];
rolePerms.forEach(p => permissions.add(p));
}
// Cache with TTL
this.cache.set(cacheKey, permissions);
setTimeout(() => this.cache.delete(cacheKey), this.ttl);
return permissions;
}
}
const cache = new PermissionCache();
const userPerms = cache.getUserPermissions(rbac, user);
```
### Minimize Permission Checks
```typescript
// ✅ Good: Check once, reuse result
function processUserActions(user: RBACUser, actions: Action[]) {
const canWrite = rbac.hasPermission(user, 'post:write');
const canDelete = rbac.hasPermission(user, 'post:delete');
return actions.map(action => {
if (action.type === 'write' && !canWrite) return null;
if (action.type === 'delete' && !canDelete) return null;
return performAction(action);
});
}
// ❌ Bad: Repeated checks
function processUserActions(user: RBACUser, actions: Action[]) {
return actions.map(action => {
// Checks permission on every iteration
if (action.type === 'write' && !rbac.hasPermission(user, 'post:write')) {
return null;
}
// ... more repeated checks
});
}
```
## Security Best Practices
### Always Validate on Server Side
```typescript
// ✅ Good: Server-side validation
// Frontend (React)
function DeleteButton({ post }) {
const { can } = useRBAC();
// UI check for better UX
if (!can('post:delete')) {
return null;
}
return Delete ;
}
// Backend (Express)
app.delete('/posts/:id',
rbacMiddleware.requirePermission('post:delete'), // ✅ Server check
async (req, res) => {
await deletePost(req.params.id);
res.json({ success: true });
}
);
// ❌ Bad: Only client-side check
// Backend without validation
app.delete('/posts/:id', async (req, res) => {
// No permission check - SECURITY VULNERABILITY!
await deletePost(req.params.id);
res.json({ success: true });
});
```
### Deny by Default
```typescript
// ✅ Good: Explicit allow, implicit deny
function canPerformAction(user: RBACUser, action: string): boolean {
// Returns false if permission not found
return rbac.hasPermission(user, action);
}
// ❌ Bad: Allow by default
function canPerformAction(user: RBACUser, action: string): boolean {
try {
return rbac.hasPermission(user, action);
} catch (error) {
return true; // DANGEROUS! Allows on error
}
}
```
### Validate User Input
```typescript
// ✅ Good: Validate and sanitize
function createRole(name: string, permissions: string[]) {
// Validate role name
if (!/^[a-z0-9-]+$/.test(name)) {
throw new Error('Invalid role name');
}
// Validate permissions exist
const validPermissions = permissions.filter(p =>
rbac.hasPermission({ id: 'system', roles: [] }, p)
);
return rbac.createRole(name, validPermissions);
}
// ❌ Bad: No validation
function createRole(name: string, permissions: string[]) {
return rbac.createRole(name, permissions); // Could inject malicious data
}
```
### Use Audit Logging
```typescript
// ✅ Good: Comprehensive audit logging
const rbac = new RBAC({
auditLogger: new BufferedAuditLogger(
async (events) => {
await db.auditLogs.insertMany(events);
// Alert on security events
const criticalEvents = events.filter(e =>
!e.allowed && e.permission.includes('admin')
);
if (criticalEvents.length > 0) {
await alertSecurityTeam(criticalEvents);
}
},
{ maxBufferSize: 100, flushIntervalMs: 5000 }
)
});
// ❌ Bad: No audit trail
const rbac = new RBAC(); // No visibility into access patterns
```
## Code Organization
### Centralize RBAC Configuration
```typescript
// ✅ Good: Single source of truth
// lib/rbac.ts
import { RBACBuilder } from '@fire-shield/core';
export const rbac = new RBACBuilder()
.useBitSystem()
.enableWildcards()
// Define all permissions
.addPermission('user:read')
.addPermission('user:write')
.addPermission('post:read')
.addPermission('post:write')
// Define all roles
.addRole('admin', ['*'])
.addRole('editor', ['post:*'])
.addRole('viewer', ['post:read'])
.build();
// Import and use everywhere
import { rbac } from '@/lib/rbac';
// ❌ Bad: Scattered configuration
// Different files creating roles differently
// file1.ts
rbac.createRole('admin', ['*']);
// file2.ts
rbac.createRole('admin', ['users:*', 'posts:*']); // Inconsistent!
```
### Use TypeScript for Type Safety
```typescript
// ✅ Good: Type-safe permissions
const PERMISSIONS = {
USER_READ: 'user:read',
USER_WRITE: 'user:write',
POST_READ: 'post:read',
POST_WRITE: 'post:write'
} as const;
type Permission = typeof PERMISSIONS[keyof typeof PERMISSIONS];
function checkPermission(user: RBACUser, permission: Permission): boolean {
return rbac.hasPermission(user, permission);
}
// ✅ Type-safe usage
checkPermission(user, PERMISSIONS.USER_READ);
// ❌ Compiler error
checkPermission(user, 'invalid:permission');
// ❌ Bad: String literals everywhere
function checkPermission(user: RBACUser, permission: string): boolean {
return rbac.hasPermission(user, permission); // No type safety
}
checkPermission(user, 'usr:raed'); // Typo not caught
```
### Document Permissions
```typescript
// ✅ Good: Well-documented permissions
const rbac = new RBACBuilder()
/**
* User Management Permissions
* Used by: Admin panel, User settings
*/
.addPermission('user:read', 1, {
description: 'View user profiles and list users',
resource: 'user',
action: 'read'
})
.addPermission('user:write', 2, {
description: 'Create and update user accounts',
resource: 'user',
action: 'write'
})
.addPermission('user:delete', 4, {
description: 'Delete user accounts (irreversible)',
resource: 'user',
action: 'delete'
})
/**
* Content Management Permissions
* Used by: CMS, Blog platform
*/
.addPermission('post:publish', 8, {
description: 'Publish posts to public site',
resource: 'post',
action: 'publish'
})
.build();
// Generate documentation
function generatePermissionDocs(rbac: RBAC) {
const permissions = rbac.getAllPermissions();
console.log('# Permission Documentation\n');
for (const perm of permissions) {
console.log(`## ${perm.name}`);
console.log(`- **Description**: ${perm.description}`);
console.log(`- **Resource**: ${perm.resource}`);
console.log(`- **Action**: ${perm.action}\n`);
}
}
```
## Testing
### Test Permission Checks
```typescript
// ✅ Good: Comprehensive permission tests
import { describe, it, expect } from 'vitest';
import { rbac } from '@/lib/rbac';
describe('RBAC Permissions', () => {
it('admin should have all permissions', () => {
const admin = { id: '1', roles: ['admin'] };
expect(rbac.hasPermission(admin, 'user:read')).toBe(true);
expect(rbac.hasPermission(admin, 'user:write')).toBe(true);
expect(rbac.hasPermission(admin, 'user:delete')).toBe(true);
});
it('viewer should only have read permissions', () => {
const viewer = { id: '2', roles: ['viewer'] };
expect(rbac.hasPermission(viewer, 'post:read')).toBe(true);
expect(rbac.hasPermission(viewer, 'post:write')).toBe(false);
expect(rbac.hasPermission(viewer, 'post:delete')).toBe(false);
});
it('should deny access when no roles assigned', () => {
const noRole = { id: '3', roles: [] };
expect(rbac.hasPermission(noRole, 'post:read')).toBe(false);
});
it('should handle wildcard permissions', () => {
const editor = { id: '4', roles: ['editor'] };
expect(rbac.hasPermission(editor, 'post:read')).toBe(true);
expect(rbac.hasPermission(editor, 'post:write')).toBe(true);
expect(rbac.hasPermission(editor, 'post:publish')).toBe(true);
});
});
```
### Test Role Hierarchy
```typescript
describe('Role Hierarchy', () => {
it('manager can act as engineer', () => {
expect(rbac.canActAsRole('manager', 'engineer')).toBe(true);
});
it('engineer cannot act as manager', () => {
expect(rbac.canActAsRole('engineer', 'manager')).toBe(false);
});
it('roles at same level cannot delegate', () => {
expect(rbac.canActAsRole('engineer', 'designer')).toBe(false);
});
});
```
### Integration Tests
```typescript
describe('API Permission Integration', () => {
it('should protect admin endpoints', async () => {
const viewer = { id: '1', roles: ['viewer'] };
const response = await request(app)
.delete('/api/users/123')
.set('Authorization', createToken(viewer));
expect(response.status).toBe(403);
expect(response.body.error).toBe('Forbidden');
});
it('should allow admin access', async () => {
const admin = { id: '2', roles: ['admin'] };
const response = await request(app)
.delete('/api/users/123')
.set('Authorization', createToken(admin));
expect(response.status).toBe(200);
});
});
```
## Error Handling
### Handle Missing Permissions Gracefully
```typescript
// ✅ Good: User-friendly error messages
function performAction(user: RBACUser, action: string) {
const result = rbac.authorize(user, action);
if (!result.allowed) {
throw new PermissionError(
`Access denied: ${result.reason}`,
{
userId: user.id,
requiredPermission: action,
userRoles: user.roles
}
);
}
// Perform action
}
class PermissionError extends Error {
constructor(message: string, public details: any) {
super(message);
this.name = 'PermissionError';
}
}
// ❌ Bad: Generic errors
function performAction(user: RBACUser, action: string) {
if (!rbac.hasPermission(user, action)) {
throw new Error('Forbidden'); // Not helpful
}
}
```
### Log Security Events
```typescript
// ✅ Good: Detailed security logging
function requirePermission(permission: string) {
return (req, res, next) => {
const result = rbac.authorize(req.user, permission);
if (!result.allowed) {
logger.warn('Permission denied', {
userId: req.user.id,
permission,
reason: result.reason,
ip: req.ip,
userAgent: req.headers['user-agent'],
path: req.path
});
return res.status(403).json({
error: 'Forbidden',
message: 'You do not have permission to perform this action'
});
}
next();
};
}
```
## Deployment
### Environment-Specific Configuration
```typescript
// ✅ Good: Environment-aware setup
const rbac = new RBACBuilder()
.useBitSystem()
.enableWildcards()
// Production: Strict mode with audit logging
.configure({
strictMode: process.env.NODE_ENV === 'production',
auditLogger: process.env.NODE_ENV === 'production'
? new DatabaseAuditLogger()
: new ConsoleAuditLogger()
})
.build();
// Development: Additional debug permissions
if (process.env.NODE_ENV === 'development') {
rbac.createRole('developer', ['*']);
}
```
### Graceful Degradation
```typescript
// ✅ Good: Fallback when RBAC unavailable
function canPerform(user: RBACUser, permission: string): boolean {
try {
return rbac.hasPermission(user, permission);
} catch (error) {
logger.error('RBAC check failed', error);
// Fail secure: deny by default
return false;
}
}
```
## Migration and Updates
### Version Your Permission Schema
```typescript
// ✅ Good: Versioned schema
interface PermissionSchemaV1 {
version: 1;
permissions: string[];
roles: Record<string, string[]>;
}
interface PermissionSchemaV2 {
version: 2;
permissions: Array<{
name: string;
bit: number;
description: string;
}>;
roles: Array<{
name: string;
permissions: string[];
level: number;
}>;
}
function migrateSchema(old: PermissionSchemaV1): PermissionSchemaV2 {
// Migration logic
return {
version: 2,
permissions: old.permissions.map((name, i) => ({
name,
bit: Math.pow(2, i),
description: ''
})),
roles: Object.entries(old.roles).map(([name, permissions], i) => ({
name,
permissions,
level: i * 10
}))
};
}
```
## Next Steps