AuthZ — The Multi-Flavor Authorization SDK

A production-grade, highly optimized authorization framework for Node.js.
Combines the power of RBAC (Role-Based Access Control) and PBAC (Policy-Based Access Control)
into a unified engine with sub-microsecond evaluation latency.

---

✨ Core Principles

1. Performance by Default — Static role resolution (O(1)) and indexed policy evaluation.
2. Framework Freedom — Core logic is fully isolated; adapters for Express, Fastify, and NestJS provide native integration without coupling.
3. Audit First — Built-in lifecycle hooks (onPreAuth / onPostAuth) for real-time security logging.
4. Developer Experience — Fluent policy builders, deep debug mode, and rich TypeScript inference.

---

📦 Packages

Package	Purpose	Version
@vynelix/authz-core	Core Engine — RBAC + PBAC logic
@vynelix/authz-express	Middleware for Express.js
@vynelix/authz-fastify	Plugin + Decorator for Fastify
@vynelix/authz-nestjs	Module + Guard for NestJS
@vynelix/authz-node	Vanilla Node.js wrapper

---

🚀 Quick Start

1. Install

# Core (required)
npm install @vynelix/authz-core

# Pick your framework adapter
npm install @vynelix/authz-express   # Express
npm install @vynelix/authz-fastify   # Fastify
npm install @vynelix/authz-nestjs    # NestJS
npm install @vynelix/authz-node      # Vanilla Node.js / Lambda

2. Create your engine

import { createAuthz, policy } from '@vynelix/authz-core';

const authz = createAuthz({
  // RBAC — hierarchical roles resolved at build time (O(1) lookups)
  roles: {
    guest:  { can: ['post.read'] },
    user:   { inherits: ['guest'], can: ['post.create'] },
    editor: { inherits: ['user'],  can: ['post.update'] },
    admin:  { can: ['*'] },
  },

  // PBAC — fine-grained policies with function or JSON conditions
  policies: [
    policy('post.update')
      .on('post')
      .when((ctx) => ctx.user.id === ctx.resource?.ownerId) // only own posts
      .build(),

    policy('post.delete')
      .deny()
      .when((ctx) => ctx.resource?.locked === true) // hard lock even for admin
      .build(),
  ],
});

3. Authorize a request

const allowed = await authz.can({
  user:     { id: 'usr_1', roles: ['editor'] },
  action:   'post.update',
  resource: { type: 'post', id: 'p42', ownerId: 'usr_1' },
});
// => true (editor role + user owns the post)

4. Use with your framework

Express

import { authorize } from '@vynelix/authz-express';

app.put('/posts/:id',
  authorize(authz, {
    action:   'post.update',
    resource: (req) => ({ type: 'post', id: req.params.id, ownerId: req.post.ownerId }),
  }),
  (req, res) => res.json({ ok: true })
);

Fastify

import { fastifyAuthz } from '@vynelix/authz-fastify';

fastify.register(fastifyAuthz, { engine: authz });

fastify.put('/posts/:id', {
  preHandler: fastify.authorize({ action: 'post.update' })
}, handler);

NestJS

@Module({ imports: [AuthzModule.forRoot({ engine: authz })] })
export class AppModule {}

@Controller('posts')
@UseGuards(AuthzGuard)
export class PostController {
  @Put(':id')
  @Authorize({ action: 'post.update', resource: 'post' })
  update() { ... }
}

---

🔍 Debug Mode

Every adapter supports debug: true which returns a full Decision object:

const decision = await authz.can(ctx, { debug: true });
// {
//   allowed: false,
//   reason: "PBAC Denied (Condition mismatch): ...",
//   matchedPolicies: ["post.update"],
//   failedConditions: ["Condition failed for policy: post.update"]
// }

---

📊 Feature Parity Matrix

Feature	Core	Express	Fastify	NestJS	Node
RBAC / PBAC Engine	✅	✅	✅	✅	✅
Per-Request Caching	✅	✅	✅	✅	✅
Audit Hooks (Pre/Post)	✅	✅	✅	✅	❌
Debug Mode	✅	✅	✅	✅	✅
Decorator Support	❌	❌	✅	✅	❌
Global Middleware	❌	✅	✅	✅	❌

---

⚡ Benchmarks

Evaluated on a standard Linux environment using tinybench.

Scenario	Ops/sec	Avg Latency
RBAC Only (100-level hierarchy)	~438,000	2.27µs
PBAC Only (100 indexed policies)	~312,000	3.19µs
Combined (No Cache)	~237,000	4.20µs
Combined + Cache Hit	~716,000	1.39µs

See performance_report.md for full methodology.

---

🆚 Why AuthZ?

Feature	AuthZ	CASL	Oso
RBAC Hierarchy	✅	⚠️	✅
PBAC / Attributes	✅	✅	✅
Deny Overrides Allow	✅	❌	✅
Serializable JSON Policies	✅	✅	❌
O(1) Role Lookup	✅	❌	❌
Per-Request Cache	✅	❌	❌
Framework Adapters	✅	⚠️	⚠️

---

📚 Documentation

Guide	Description
Getting Started	Installation, first engine, first check
RBAC Guide	Roles, inheritance, wildcards
PBAC Guide	Policies, conditions, deny rules
Custom Engine	Implementing AuthorizationEngine

---

🧪 Examples

Working runnable apps in authz-examples/:

• Express — RBAC + PBAC + audit hooks
• Fastify — Plugin + preHandler decorator
• NestJS — Module + Guard + @Authorize decorator

---

🗺️ Roadmap

• Redis Cache Provider — Shared cache for multi-instance deployments
• AuthZ Dashboard — Visual policy editor and real-time audit viewer
• Rust/WASM Core — WASM-based engine for maximum performance

---

🤝 Contributing

See CONTRIBUTING.md for how to set up the monorepo, run tests, and submit pull requests.

---

License

MIT © 2026 Engr., Isaiah Pius