@apio/authentication-utils

A lightweight utility library for handling role-based authorization checks in Apio IoT applications.

Table of Contents

• Installation
• Usage
  • CommonJS
  • ES Modules
• API Reference
• Authorization System
  • Permission Format
  • Wildcard Permissions
  • Negated Permissions
• Examples
• Type Definitions
• Contributing
• License

Installation

npm install @apio/authentication-utils

or using yarn:

yarn add @apio/authentication-utils

Usage

This package supports both CommonJS and ES Module imports.

CommonJS

const { hasAuthorization } = require('@apio/authentication-utils');

ES Modules

import { hasAuthorization } from '@apio/authentication-utils';

API Reference

hasAuthorization(wantedAuthorizations, authorizations, projectId)

Checks if a user has the required permissions for a specific project.

Parameters

• wantedAuthorizations {Array<String>|String} - The permission(s) to check for. Can be a single string or an array of strings.
• authorizations {Array<Role>} - Array of role objects containing user's permissions for different projects.
• projectId {String} - The ID of the project to check permissions for.

Returns

• {Boolean} - Returns true if the user has all the requested permissions, false otherwise.

Authorization System

Permission Format

Permissions follow a dot-notation format, typically structured as:

domain.resource.action

Examples:

• apio.core.plants.read
• apio.core.plants.write
• apio.admin.users.delete

Wildcard Permissions

The system supports wildcard permissions using the * character:

• apio.core.* - Grants all permissions under apio.core
• apio.core.plants.* - Grants all actions on plants
• * - Grants all permissions (superadmin)

Negated Permissions

Permissions can be negated by prefixing them with -. Negated permissions take precedence over positive permissions:

permissions: [
  'apio.core.*',        // Grants all core permissions
  '-apio.core.plants.delete'  // Except deleting plants
]

Examples

Basic Usage

const hasAuthorization = require('@apio/authentication-utils');

const userRoles = [
  {
    projectId: 'project-123',
    permissions: ['apio.core.plants.read', 'apio.core.plants.write']
  },
  {
    projectId: 'project-456',
    permissions: ['apio.core.*', '-apio.core.users.delete']
  }
];

// Check single permission
const canRead = hasAuthorization('apio.core.plants.read', userRoles, 'project-123');
console.log(canRead); // true

// Check multiple permissions
const canManage = hasAuthorization(
  ['apio.core.plants.read', 'apio.core.plants.write'],
  userRoles,
  'project-123'
);
console.log(canManage); // true

// Check permission that doesn't exist
const canDelete = hasAuthorization('apio.core.plants.delete', userRoles, 'project-123');
console.log(canDelete); // false

Wildcard Example

const adminRoles = [
  {
    projectId: 'project-789',
    permissions: ['apio.core.*']  // Has all core permissions
  }
];

Negated Permissions Example

const limitedAdminRoles = [
  {
    projectId: 'project-999',
    permissions: [
      'apio.*',           // All permissions
      '-apio.admin.*',    // Except admin permissions
      '-apio.core.users.delete'  // And cannot delete users
    ]
  }
];

const canDeleteUsers = hasAuthorization(
  'apio.core.users.delete',
  limitedAdminRoles,
  'project-999'
);
console.log(canDeleteUsers); // false

const canReadPlants = hasAuthorization(
  'apio.core.plants.read',
  limitedAdminRoles,
  'project-999'
);
console.log(canReadPlants); // true

Type Definitions

Role Object Structure

interface Role {
  projectId: string;
  permissions: string[];
}

Function Signature

function hasAuthorization(
  wantedAuthorizations: string | string[],
  authorizations: Role[],
  projectId: string
): boolean;

Best Practices

1. Use specific permissions when possible rather than wildcards for better security control.
2. Order matters for negated permissions - they always take precedence.
3. Case-insensitive - All permission checks are case-insensitive for consistency.
4. Validate inputs - The function filters out non-string permissions automatically.

Error Handling

The function handles edge cases gracefully:

• Returns false if no role is found for the specified project
• Filters out invalid (non-string) permissions
• Handles single string or array input for wantedAuthorizations

Contributing

Contributions are welcome! Please feel free to submit a Pull Request to the GitHub repository.

License

ISC © Apio IoT