ACEiffy Node.js SDK

The official Node.js / TypeScript client for integrating with the ACEiffy Authorization Engine. Make context-aware ABAC (Attribute-Based Access Control) authorization decisions directly from your Node.js backend.

Installation

npm install # Make sure dependencies like axios are installed
npm run build

Setup

Initialize the client with your engine URL and the Tenant ID for your application:

import { AceiffyClient } from 'aceiffy-sdk';

const aceiffy = new AceiffyClient({
    baseUrl: "http://localhost:8080", // URL of your running ACEiffy Go backend
    tenantId: "your-tenant-id",       // e.g., 'demo-tenant'
    // apiKey: "your-secret-api-key" // Optional API Key
});

Features

1. Manual Check (authorize)

Manually verify if a user (principal) can perform a specific action on a resource, passing optional ABAC dynamic contextual attributes.

const decision = await aceiffy.authorize(
    "intern_user",               // Principal ID
    "ec2:TerminateInstance",     // Action
    "arn:aws:ec2:::instance/1",  // Resource URN
    { environment: "development" } // Context (ABAC)
);

if (decision.allowed) {
    console.log("Allowed!");
} else {
    console.error("Denied:", decision.reason, `(Code: ${decision.policyCode})`);
}

2. Express Middleware (requirePermission)

Easily protect your Express routes. The middleware automatically blocks requests if the ACEiffy engine denies access and handles sending the 403 Forbidden payload back to the client.

import express from 'express';
const app = express();

app.post('/api/instances/terminate', 
    aceiffy.requirePermission(
        'ec2:TerminateInstance', 
        (req) => 'arn:aws:ec2:::instance/' + req.body.instanceId,
        (req) => ({ environment: req.body.environment })
    ),
    (req, res) => {
        // This will only execute if ACEiffy engine returned "allow"
        res.status(200).json({ message: "Instance terminated." });
    }
);

Note: The express middleware expects the caller's ID to be provided in the x-user-id HTTP header.

Failure Safe

The SDK is designed to fail-closed. If the ACEiffy Engine is unreachable or times out, the client automatically defaults to a secure deny decision and handles it gracefully.