The official Node.js SDK for Permguard

The Permguard Node.js SDK provides a simple and flexible client to perform authorization checks against a Permguard Policy Decision Point (PDP) service using gRPC. Please refer to the Permguard Documentation for more information.

Prerequisites

• Node.js 20.x or later
• TypeScript 5.8 or later (if using TypeScript)

Installation

Run the following command to install the SDK:

npm install permguard

or with Yarn:

yarn add permguard

Usage Example

Below is a sample TypeScript code demonstrating how to create a Permguard client, build an authorization request using a builder pattern, and process the authorization response:

import {
  PrincipalBuilder,
  AZAtomicRequestBuilder,
  withEndpoint,
  AZClient,
} from "permguard";

// Create a new Permguard client
const azClient = new AZClient(withEndpoint("localhost", 9094));

// Create the Principal
const principal = new PrincipalBuilder("[email protected]").build();

// Create the entities
const entities = [
  {
    uid: {
      type: "MagicFarmacia::Platform::BranchInfo",
      id: "subscription",
    },
    attrs: {
      active: true,
    },
    parents: [],
  },
];

// Create a new authorization request
const req = new AZAtomicRequestBuilder(
  583438038653,
  "46706cb00ea248d6841cfe2c9f02205b",
  "platform-creator",
  "MagicFarmacia::Platform::Subscription",
  "MagicFarmacia::Platform::Action::create"
)
  .withRequestID("1234")
  .withPrincipal(principal)
  .withEntitiesItems("cedar", entities)
  .withSubjectRoleActorType()
  .withSubjectSource("keycloack")
  .withSubjectProperty("isSuperUser", true)
  .withResourceID("e3a786fd07e24bfa95ba4341d3695ae8")
  .withResourceProperty("isEnabled", true)
  .withActionProperty("isEnabled", true)
  .withContextProperty("time", "2025-01-23T16:17:46+00:00")
  .withContextProperty("isSubscriptionActive", true)
  .build();

// Check the authorization
const { decision, response } = await azClient.check(req);
if (decision) {
  console.log("✅ Authorization Permitted");
} else {
  console.log("❌ Authorization Denied");
  if (response) {
    if (response.Context?.ReasonAdmin) {
      console.log(`-> Reason Admin: ${response.Context.ReasonAdmin.Message}`);
    }
    if (response.Context?.ReasonUser) {
      console.log(`-> Reason User: ${response.Context.ReasonUser.Message}`);
    }
    for (const evaluation of response.Evaluations || []) {
      if (evaluation.Context?.ReasonAdmin) {
        console.log(
          `-> Reason Admin: ${evaluation.Context.ReasonAdmin.Message}`
        );
      }
      if (evaluation.Context?.ReasonUser) {
        console.log(`-> Reason User: ${evaluation.Context.ReasonUser.Message}`);
      }
    }
  }
}

Version Compatibility

Our SDK follows a versioning scheme aligned with the PermGuard server versions to ensure seamless integration. The versioning format is as follows:

SDK Versioning Format: x.y.z

• x.y: Indicates the compatible PermGuard server version.
• z: Represents the SDK's patch or minor updates specific to that server version.

Compatibility Examples:

• SDK Version 1.3.0 is compatible with PermGuard Server 1.3.
• SDK Version 1.3.1 includes minor improvements or bug fixes for PermGuard Server 1.3.

Incompatibility Example:

• SDK Version 1.3.0 may not be guaranteed to be compatible with PermGuard Server 1.4 due to potential changes introduced in server version 1.4.

Important: Ensure that the major and minor versions (x.y) of the SDK match those of your PermGuard server to maintain compatibility.

Created by Nitro Agility.