ABAC Docs
Core Package

@devcraft-ts/abac-admin-core

Lightweight, framework-agnostic core for ABAC Policy Administration. Built on top of abac-engine with full TypeScript support.

Built on abac-engine

This package uses official abac-engine types, schemas, and utilities. The core provides the management layer for policies, while abac-engine handles evaluation. Learn more →

Ultra-Lightweight

~15kb minified+gzipped with zero UI dependencies

Framework Agnostic

Works with any JavaScript environment

Type-Safe

Full TypeScript support with Zod validation and abac-engine types

abac-engine Integration

Uses official abac-engine schemas and evaluation logic

Installation

npm install @devcraft-ts/abac-admin-core zod

# or
yarn add @devcraft-ts/abac-admin-core zod

# or
pnpm add @devcraft-ts/abac-admin-core zod

Quick Start

Initialize the Client

import { ABACAdminClient, PolicyService } from '@devcraft-ts/abac-admin-core';

const client = new ABACAdminClient({
  baseURL: 'https://api.example.com/abac',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const policyService = new PolicyService(client);

Working with Policies

// List all policies
const policies = await policyService.list();

// Get a specific policy
const policy = await policyService.get('policy-id');

// Create a new policy
const newPolicy = await policyService.create({
  policyId: 'my-policy',
  version: '1.0.0',
  effect: 'PERMIT',
  description: 'Allow users to view documents',
  conditions: {
    type: 'equals',
    left: { category: 'action', key: 'type' },
    right: 'view'
  },
  isActive: true,
  category: 'document',
  tags: ['document', 'read'],
  createdBy: 'user-123'
});

// Update a policy
const updated = await policyService.update('policy-id', {
  description: 'Updated description'
});

// Activate/Deactivate
await policyService.activate('policy-id');
await policyService.deactivate('policy-id');

// Delete a policy
await policyService.delete('policy-id');

ABACAdminClient

The base HTTP client for all API operations.

const client = new ABACAdminClient({
  baseURL: string;           // Required: API base URL
  headers?: Record<string, string>;  // Optional: Custom headers
  timeout?: number;          // Optional: Request timeout (default: 30000ms)
  onError?: (error: Error) => void;  // Optional: Error handler
  onSuccess?: (response: Response) => void;  // Optional: Success handler
});

PolicyService

Service for managing policies with full CRUD operations.

Methods

list(filters?: PolicyFilters): Promise<Policy[]>

List policies with optional filtering

get(id: string): Promise<Policy>

Get a single policy by ID

create(policy: PolicyInput): Promise<Policy>

Create a new policy

update(id: string, policy: PolicyUpdate): Promise<Policy>

Update an existing policy

delete(id: string): Promise<void>

Delete a policy

test(request: PolicyTestRequest): Promise<PolicyTestResult>

Test a policy against sample data

AttributeService

Service for managing resource attributes.

import { AttributeService } from '@devcraft-ts/abac-admin-core';

const attributeService = new AttributeService(client);

// Get all attributes for a resource
const attributes = await attributeService.getResourceAttributes(
  'user',
  'user-123'
);

// Set a single attribute
await attributeService.setResourceAttribute(
  'user',
  'user-123',
  'department',
  'engineering'
);

// Bulk set attributes
await attributeService.bulkSetAttributes('user', 'user-123', {
  department: 'engineering',
  role: 'senior-engineer',
  level: 5
});

// Get attribute history
const history = await attributeService.getHistory(
  'user',
  'user-123',
  'role'
);

// Compare attributes between resources
const comparison = await attributeService.compareAttributes(
  'user',
  'user-123',
  'user-456'
);

AuditService

Service for retrieving audit logs and statistics.

import { AuditService } from '@devcraft-ts/abac-admin-core';

const auditService = new AuditService(client);

// Get audit log with filters
const auditLog = await auditService.getAuditLog({
  entityType: 'policy',
  action: 'UPDATE',
  startDate: '2024-01-01T00:00:00Z',
  limit: 50
});

// Get entity history
const policyHistory = await auditService.getEntityHistory(
  'policy',
  'policy-id'
);

// Get user activity
const userActivity = await auditService.getUserActivity('user-123', {
  startDate: '2024-01-01T00:00:00Z',
  limit: 100
});

// Get statistics
const stats = await auditService.getStatistics();

ConditionBuilder

Utility class for building policy conditions.

import { ConditionBuilder } from '@devcraft-ts/abac-admin-core';

// Simple condition
const condition1 = ConditionBuilder.equals(
  ConditionBuilder.attr('subject', 'role'),
  'admin'
);

// Complex condition with AND/OR
const condition2 = ConditionBuilder.and(
  ConditionBuilder.equals(
    ConditionBuilder.attr('subject', 'department'),
    'engineering'
  ),
  ConditionBuilder.or(
    ConditionBuilder.in(
      ConditionBuilder.attr('subject', 'role'),
      ['admin', 'manager']
    ),
    ConditionBuilder.gte(
      ConditionBuilder.attr('subject', 'level'),
      5
    )
  )
);

// Available operators:
// - equals, notEquals, in, notIn
// - gte, gt, lte, lt
// - contains, startsWith, endsWith, matches
// - and, or, not

Validators & Formatters

Validators

import {
  validatePolicyId,
  validateVersion,
  validatePolicyStructure,
  validateConditionStructure,
  validateAttributeKey
} from '@devcraft-ts/abac-admin-core';

// Validate policy ID format
const isValid = validatePolicyId('my-policy');

// Validate version string
const isValidVersion = validateVersion('1.0.0');

// Validate entire policy
const result = validatePolicyStructure(policy);
if (!result.valid) {
  console.error(result.errors);
}

Formatters

import {
  formatDate,
  formatRelativeTime,
  formatPolicyEffect,
  formatCondition
} from '@devcraft-ts/abac-admin-core';

// Format dates
formatDate('2024-01-15T10:30:00Z');
// "Jan 15, 2024, 10:30 AM"

// Relative time
formatRelativeTime('2024-01-15T10:30:00Z');
// "2 hours ago"

// Format policy effect
formatPolicyEffect('PERMIT');
// "Permit"

// Format condition for display
formatCondition(condition);

Error Handling

// Wrap API calls in try-catch
try {
  const policy = await policyService.get('policy-id');
} catch (error) {
  if (error instanceof Error) {
    console.error('API Error:', error.message);
  }
}

// Global error handler
const client = new ABACAdminClient({
  baseURL: 'https://api.example.com',
  onError: (error) => {
    console.error('ABAC API Error:', error);
    // Send to error tracking service
  }
});

TypeScript Support

import type {
  // Policy types
  Policy,
  PolicyInput,
  PolicyUpdate,
  PolicyEffect,
  Condition,
  ConditionType,
  AttributeRef,

  // Attribute types
  AttributeValue,
  AttributeDefinition,
  ResourceType,
  AttributeValueType,

  // Audit types
  AuditLogEntry,
  AuditAction,
  AuditLogFilter,

  // API types
  PolicyFilters,
  PolicyTestRequest,
  PolicyTestResult,
  AuditLogResponse,
  AuditStatistics
} from '@devcraft-ts/abac-admin-core';

Next Steps

React Hooks

Use headless React hooks for UI integration

Next.js Utils

Server-side utilities for Next.js apps

React UI

Pre-built UI components