🚀 Authz-Engine: The O(1) Authorization Supernova

High-Performance Hierarchical RBAC. Zero Latency. Infinite Scale.

authz-engine isn't a simple permission checker; it's a compiler for access control. It ingests your high-level intent and "detonates" it into a flat, O(1) reachability mesh that resolves any complex permission query in less than 0.1ms.

📦 Installation

npm install authz-engine

💥 The "Expansion" Effect: From 5 Lines to 100+ Nodes

Define your modules once. The engine automatically expands them across two dimensions of authority, creating a "Universal Coverage Mesh."

flowchart LR
    subgraph Config ["1. Your Intent (The Spark)"]
        direction TB
        C["{ modules: { store: ['orders'] } }"]
    end

    subgraph Expansion ["2. Automated Detonation (The Supernova)"]
        direction TB
        
        %% The Explosive Growth
        G_DEL["*:delete"] ==> M_DEL["store:delete"]
        M_DEL ==> R_DEL["store.orders:delete"]
        
        %% The Cascade
        R_DEL --> R_UPD["store.orders:update"]
        R_UPD --> R_CRT["store.orders:create"]
        R_CRT --> R_READ["store.orders:read"]

        %% Cross-Links
        M_DEL -.-> R_READ
        G_DEL -.-> R_READ
    end

    subgraph Mesh ["3. The O(1) Fabric (The Rocket)"]
        direction TB
        F["Flat Bit-Map / Hash Table"]
    end

    Config --> Expansion
    Expansion --> Mesh

The Rocket Power: One line of config (store: ['orders']) generates a 4-tier hierarchy across every CRUD action. Granting a single "Root" permission instantly secures the entire sub-tree without manual mapping.

🏎️ Performance: Breaking the Latency Wall

Most authorization libraries fail as you scale. authz-engine uses Transitive Closure (Floyd-Warshall) to ensure that whether you have 10 permissions or 10,000, the check time is identical.

flowchart LR
    subgraph Scaling ["Latency vs. Complexity"]
        direction LR
        L1["Depth: 1"] --> P1["< 0.1ms"]
        L2["Depth: 100"] --> P2["< 0.1ms"]
        L3["Roles: 1000"] --> P3["< 0.1ms"]
    end
    
    style P1 fill:#00e676,stroke:#333
    style P2 fill:#00e676,stroke:#333
    style P3 fill:#00e676,stroke:#333

🛠️ The "Fluent" Command Center

Stop guessing string names. The engine's Proxy API provides a type-safe, semantic interface that acts as your IDE's co-pilot.

const rbac = new PermissionService(config);

// 1. Semantic Clarity: 'readStoreOrders' is auto-generated
// 2. Performance: O(1) lookup
// 3. Resilience: Typo-protection via Proxy
if (rbac.can.readStoreOrders(userPermissions)) {
  // Access granted instantly
}

🧠 Architectural Deep Dive: The Compiler Strategy

The engine treats your RBAC configuration like source code and compiles it into an optimized runtime artifact.

sequenceDiagram
    autonumber
    participant App as App Startup
    participant Engine as FW Compiler
    participant Table as Reachability Table
    participant Req as API Request

    App->>Engine: Load modules & roles
    Note over Engine: Running Floyd-Warshall O(N³)
    Engine->>Table: Flattens Graph (Transitive Closure)
    Note over Table: Every possible "A grants B" is recorded
    
    Note over Req, Table: Runtime Phase
    Req->>Table: "can Admin read Orders?"
    Table-->>Req: YES (Direct Hash Lookup)

Structural Insight: By shifting the computational "heavy lifting" to the startup phase, we eliminate the recursive "Graph Walk of Death" that plagues traditional authorization systems.

📊 System Statistics

Auditing your security posture is built-in.

| Metric | Description | Advantage | | :--- | :--- | :--- | | Total Permissions | Every auto-generated node | Full coverage visibility | | Grant Relationships | Total edges in the mesh | Understand your "Blast Radius" | | Resolution Speed | Time per check | Predictable <0.1ms |

License

MIT