{"_id":"@apio/authentication-utils","_rev":"2-451940bcff25f663e144cf93fb4a806b","name":"@apio/authentication-utils","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@apio/authentication-utils","version":"1.0.0","keywords":[],"author":"","license":"ISC","_id":"@apio/authentication-utils@1.0.0","maintainers":[{"name":"fatmatto","email":"cikkense@gmail.com"},{"name":"matteodisabatino","email":"matteo.di.sabatino.1989@gmail.com"},{"name":"gprovinciali","email":"gianluigi.provinciali@gmail.com"},{"name":"davidecantelmi","email":"d.cantelmi@apio.cc"}],"homepage":"https://github.com/ApioIoT/authentication-utils#readme","bugs":{"url":"https://github.com/ApioIoT/authentication-utils/issues"},"dist":{"shasum":"5d48fbf223de56d0ca1c03b46635bf396ec3002a","tarball":"https://registry.npmjs.org/@apio/authentication-utils/-/authentication-utils-1.0.0.tgz","fileCount":7,"integrity":"sha512-ipMhR2TSr+YUnN5NvfyHE6O6IAPOdyWFH8mii8Nt8VRAUnnyaO/BhgwRiJzFo2L4tHgnsrKDDXafiH+dF92pxQ==","signatures":[{"sig":"MEQCIEsnvwq2YZmk1ghoF2IV4jnSdFG63GRCmEbLmQWmCqFHAiADXobuYMMb8uT0vCSnhqJlqz9yONPnGORUwFNV0+wivA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":14385},"main":"index.js","gitHead":"1f8812521b094480b910b73054957fa88ac29dc9","scripts":{"test":"node --test --experimental-test-coverage ./test/*.spec.js","prepare":"husky"},"_npmUser":{"name":"davidecantelmi","email":"d.cantelmi@apio.cc"},"repository":{"url":"git+https://github.com/ApioIoT/authentication-utils.git","type":"git"},"_npmVersion":"10.9.2","description":"A lightweight utility library for handling role-based authorization checks in Apio IoT applications.","directories":{},"_nodeVersion":"22.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","eslint":"^9.31.0","neostandard":"^0.12.2"},"_npmOperationalInternal":{"tmp":"tmp/authentication-utils_1.0.0_1753455678420_0.0005016330547236159","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@apio/authentication-utils","version":"1.1.0","main":"index.js","scripts":{"test":"node --test --experimental-test-coverage ./test/*.spec.js","prepare":"husky"},"repository":{"type":"git","url":"git+https://github.com/ApioIoT/authentication-utils.git"},"publishConfig":{"access":"public"},"keywords":[],"author":"","license":"ISC","bugs":{"url":"https://github.com/ApioIoT/authentication-utils/issues"},"homepage":"https://github.com/ApioIoT/authentication-utils#readme","description":"A lightweight utility library for handling role-based authorization checks in Apio IoT applications.","devDependencies":{"eslint":"^9.31.0","husky":"^9.1.7","neostandard":"^0.12.2"},"_id":"@apio/authentication-utils@1.1.0","gitHead":"c231623792f9c444e181f91e351d5f82e28c0c58","_nodeVersion":"20.19.2","_npmVersion":"11.5.2","dist":{"integrity":"sha512-T1aowSjh5VuF7MYH4fJ/iENZPO4jAZ+1q+aiyRgzyNf0ushRgHu0ic4n53h+RgCLTc5NssujYOUv96lRObqruw==","shasum":"2ddf6206c5cb433acd4d6042c1a653c8f623955e","tarball":"https://registry.npmjs.org/@apio/authentication-utils/-/authentication-utils-1.1.0.tgz","fileCount":7,"unpackedSize":25958,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE2THkd+StxIWN7gQmzeueUhV8ncciv9xQLlOiUEIWDmAiEAieRM7KO5nhMZerZFrk2oQp447VVTvAqJJWEn+aIpvjA="}]},"_npmUser":{"name":"davidecantelmi","email":"d.cantelmi@apio.cc"},"directories":{},"maintainers":[{"name":"fatmatto","email":"cikkense@gmail.com"},{"name":"matteodisabatino","email":"matteo.di.sabatino.1989@gmail.com"},{"name":"gprovinciali","email":"gianluigi.provinciali@gmail.com"},{"name":"davidecantelmi","email":"d.cantelmi@apio.cc"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/authentication-utils_1.1.0_1755096763734_0.8828576146927132"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-25T15:01:18.330Z","modified":"2025-08-13T14:52:44.115Z","1.0.0":"2025-07-25T15:01:18.591Z","1.1.0":"2025-08-13T14:52:43.892Z"},"bugs":{"url":"https://github.com/ApioIoT/authentication-utils/issues"},"license":"ISC","homepage":"https://github.com/ApioIoT/authentication-utils#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/ApioIoT/authentication-utils.git"},"description":"A lightweight utility library for handling role-based authorization checks in Apio IoT applications.","maintainers":[{"name":"fatmatto","email":"cikkense@gmail.com"},{"name":"matteodisabatino","email":"matteo.di.sabatino.1989@gmail.com"},{"name":"gprovinciali","email":"gianluigi.provinciali@gmail.com"},{"name":"davidecantelmi","email":"d.cantelmi@apio.cc"}],"readme":"# @apio/authentication-utils\n\nA lightweight utility library for handling role-based authorization checks in Apio IoT applications.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [CommonJS](#commonjs)\n  - [ES Modules](#es-modules)\n- [API Reference](#api-reference)\n- [Authorization System](#authorization-system)\n  - [Permission Format](#permission-format)\n  - [Wildcard Permissions](#wildcard-permissions)\n  - [Negated Permissions](#negated-permissions)\n- [Examples](#examples)\n- [Type Definitions](#type-definitions)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm install @apio/authentication-utils\n```\n\nor using yarn:\n\n```bash\nyarn add @apio/authentication-utils\n```\n\n## Usage\n\nThis package supports both CommonJS and ES Module imports.\n\n### CommonJS\n\n```javascript\nconst { hasAuthorization } = require('@apio/authentication-utils');\n```\n\n### ES Modules\n\n```javascript\nimport { hasAuthorization } from '@apio/authentication-utils';\n```\n\n## API Reference\n\n### `hasAuthorization(wantedAuthorizations, authorizations, projectId)`\n\nChecks if a user has the required permissions for a specific project.\n\n#### Parameters\n\n- **`wantedAuthorizations`** `{Array<String>|String}` - The permission(s) to check for. Can be a single string or an array of strings.\n- **`authorizations`** `{Array<Role>}` - Array of role objects containing user's permissions for different projects.\n- **`projectId`** `{String}` - The ID of the project to check permissions for.\n\n#### Returns\n\n- **`{Boolean}`** - Returns `true` if the user has all the requested permissions, `false` otherwise.\n\n## Authorization System\n\n### Permission Format\n\nPermissions follow a dot-notation format, typically structured as:\n```\ndomain.resource.action\n```\n\nExamples:\n- `apio.core.plants.read`\n- `apio.core.plants.write`\n- `apio.admin.users.delete`\n\n### Wildcard Permissions\n\nThe system supports wildcard permissions using the `*` character:\n\n- `apio.core.*` - Grants all permissions under `apio.core`\n- `apio.core.plants.*` - Grants all actions on plants\n- `*` - Grants all permissions (superadmin)\n\n### Negated Permissions\n\nPermissions can be negated by prefixing them with `-`. Negated permissions take precedence over positive permissions:\n\n```javascript\npermissions: [\n  'apio.core.*',        // Grants all core permissions\n  '-apio.core.plants.delete'  // Except deleting plants\n]\n```\n\n## Examples\n\n### Basic Usage\n\n```javascript\nconst hasAuthorization = require('@apio/authentication-utils');\n\nconst userRoles = [\n  {\n    projectId: 'project-123',\n    permissions: ['apio.core.plants.read', 'apio.core.plants.write']\n  },\n  {\n    projectId: 'project-456',\n    permissions: ['apio.core.*', '-apio.core.users.delete']\n  }\n];\n\n// Check single permission\nconst canRead = hasAuthorization('apio.core.plants.read', userRoles, 'project-123');\nconsole.log(canRead); // true\n\n// Check multiple permissions\nconst canManage = hasAuthorization(\n  ['apio.core.plants.read', 'apio.core.plants.write'],\n  userRoles,\n  'project-123'\n);\nconsole.log(canManage); // true\n\n// Check permission that doesn't exist\nconst canDelete = hasAuthorization('apio.core.plants.delete', userRoles, 'project-123');\nconsole.log(canDelete); // false\n```\n\n### Wildcard Example\n\n```javascript\nconst adminRoles = [\n  {\n    projectId: 'project-789',\n    permissions: ['apio.core.*']  // Has all core permissions\n  }\n];\n```\n\n### Negated Permissions Example\n\n```javascript\nconst limitedAdminRoles = [\n  {\n    projectId: 'project-999',\n    permissions: [\n      'apio.*',           // All permissions\n      '-apio.admin.*',    // Except admin permissions\n      '-apio.core.users.delete'  // And cannot delete users\n    ]\n  }\n];\n\nconst canDeleteUsers = hasAuthorization(\n  'apio.core.users.delete',\n  limitedAdminRoles,\n  'project-999'\n);\nconsole.log(canDeleteUsers); // false\n\nconst canReadPlants = hasAuthorization(\n  'apio.core.plants.read',\n  limitedAdminRoles,\n  'project-999'\n);\nconsole.log(canReadPlants); // true\n```\n\n## Type Definitions\n\n### Role Object Structure\n\n```typescript\ninterface Role {\n  projectId: string;\n  permissions: string[];\n}\n```\n\n### Function Signature\n\n```typescript\nfunction hasAuthorization(\n  wantedAuthorizations: string | string[],\n  authorizations: Role[],\n  projectId: string\n): boolean;\n```\n\n## Best Practices\n\n1. **Use specific permissions** when possible rather than wildcards for better security control.\n2. **Order matters** for negated permissions - they always take precedence.\n3. **Case-insensitive** - All permission checks are case-insensitive for consistency.\n4. **Validate inputs** - The function filters out non-string permissions automatically.\n\n## Error Handling\n\nThe function handles edge cases gracefully:\n- Returns `false` if no role is found for the specified project\n- Filters out invalid (non-string) permissions\n- Handles single string or array input for `wantedAuthorizations`\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request to the [GitHub repository](https://github.com/ApioIoT/authentication-utils).\n\n## License\n\nISC © Apio IoT\n","readmeFilename":"README.md"}