{"id":23763474,"url":"https://github.com/chaqchase/iamjs","last_synced_at":"2025-09-05T08:32:55.475Z","repository":{"id":157881400,"uuid":"627597934","full_name":"chaqchase/iamjs","owner":"chaqchase","description":"iamjs - Your complete Access Control Library with End-to-end typesafety","archived":false,"fork":false,"pushed_at":"2024-10-14T19:53:08.000Z","size":2320,"stargazers_count":27,"open_issues_count":5,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-28T20:44:28.515Z","etag":null,"topics":["abac","access-control","access-control-library","acl","attribute","attribute-based-access-control","auth","authorization","authorization-library","express","iamjs","koa","nextjs","permissions","rbac","react","role-based-access-control","roles"],"latest_commit_sha":null,"homepage":"https://iamjs.achaq.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chaqchase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-13T19:53:18.000Z","updated_at":"2025-05-07T12:50:35.000Z","dependencies_parsed_at":"2023-12-04T07:26:35.474Z","dependency_job_id":"e1fd5b53-f48f-42ab-bf82-fbce89ad18e5","html_url":"https://github.com/chaqchase/iamjs","commit_stats":{"total_commits":249,"total_committers":3,"mean_commits":83.0,"dds":"0.31726907630522083","last_synced_commit":"0f41b633cbd0755524d6ed99252922ee3c2efac0"},"previous_names":["chaqchase/iamjs","triyanox/iamjs"],"tags_count":199,"template":false,"template_full_name":null,"purl":"pkg:github/chaqchase/iamjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Fiamjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Fiamjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Fiamjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Fiamjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chaqchase","download_url":"https://codeload.github.com/chaqchase/iamjs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Fiamjs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273438895,"owners_count":25105855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abac","access-control","access-control-library","acl","attribute","attribute-based-access-control","auth","authorization","authorization-library","express","iamjs","koa","nextjs","permissions","rbac","react","role-based-access-control","roles"],"created_at":"2024-12-31T22:12:32.090Z","updated_at":"2025-09-05T08:32:50.411Z","avatar_url":"https://github.com/chaqchase.png","language":"TypeScript","readme":"\u003cimg src=\"https://raw.githubusercontent.com/triyanox/iamjs/main/assets/logo.png\" alt=\"iamjs logo\" title=\"iamjs\" align=\"right\" height=\"50\" width=\"50\"/\u003e\n\n# iamjs - Your Complete Access Control Library with End-to-End Type Safety\n\n\u003cimg src=\"https://raw.githubusercontent.com/triyanox/iamjs/main/assets/banner.png\" alt=\"iamjs banner\"\ntitle=\"iamjs\" align=\"center\" height=\"auto\" width=\"100%\"/\u003e\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Documentation](#documentation)\n- [Quick Start Guide](#quick-start-guide)\n  - [Creating a Role](#creating-a-role)\n  - [Creating a Schema](#creating-a-schema)\n  - [Using with Express.js](#using-with-expressjs)\n- [Framework Support](#framework-support)\n- [Advanced Usage](#advanced-usage)\n- [Best Practices](#best-practices)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\niamjs is a fully-featured and type-safe library that simplifies authorization in JavaScript and TypeScript applications. Designed for versatility, it supports both Node.js and browser environments, making it an ideal choice for a wide range of projects, from server-side applications to complex front-end systems.\n\n## Key Features\n\n- **End-to-End Type Safety**: Leverage TypeScript for robust type checking across your entire authorization system.\n- **Flexible Role-Based Access Control (RBAC)**: Define granular permissions with ease.\n- **Framework Agnostic**: Core functionality that can be used with any JavaScript framework.\n- **Dedicated Framework Support**: Pre-built integrations for popular frameworks like Express, Koa, Next.js, and React.\n- **Custom Permissions**: Extend beyond basic CRUD operations with custom action definitions.\n- **Activity Logging**: Built-in support for logging authorization activities.\n\n## Installation\n\niamjs offers multiple packages to suit your specific needs:\n\n```bash\n# For Express.js applications\nnpm install @iamjs/core @iamjs/express\n\n# For Koa applications\nnpm install @iamjs/core @iamjs/koa\n\n# For Next.js applications\nnpm install @iamjs/core @iamjs/next\n\n# For React applications\nnpm install @iamjs/core @iamjs/react\n\n# For framework-agnostic use\nnpm install @iamjs/core\n```\n\n## Documentation\n\nFor comprehensive documentation, including advanced features and API references, visit our [official documentation site](https://iamjs.achaq.dev/).\n\n## Quick Start Guide\n\n### Creating a Role\n\nDefine roles with specific permissions using the `Role` class:\n\n```typescript\nimport { Role } from '@iamjs/core';\n\nconst userRole = new Role({\n  name: 'user',\n  description: 'Standard user role',\n  meta: {\n    createdAt: new Date(),\n    updatedAt: new Date()\n  },\n  config: {\n    posts: {\n      base: 'crudl',\n      custom: {\n        publish: true,\n        feature: false\n      }\n    },\n    comments: {\n      base: 'crud-'\n    }\n  }\n});\n```\n\nThis example creates a 'user' role with permissions for 'posts' and 'comments' resources. The 'base' property uses CRUD notation (create, read, update, delete, list), while 'custom' allows for additional specific actions.\n\n### Creating a Schema\n\nGroup roles into a schema for easier management:\n\n```typescript\nimport { Schema } from '@iamjs/core';\n\nconst schema = new Schema({\n  roles: { \n    user: userRole,\n    admin: adminRole // Assuming you've defined an adminRole\n  }\n});\n```\n\n### Using with Express.js\n\nIntegrate iamjs into an Express.js application:\n\n```typescript\nimport express from 'express';\nimport { ExpressRoleManager } from '@iamjs/express';\n\nconst app = express();\n\nconst roleManager = new ExpressRoleManager({\n  schema,\n  onError: (err, req, res, next) =\u003e {\n    res.status(403).json({ error: 'Access Denied', details: err.message });\n  },\n  onSuccess: (req, res, next) =\u003e {\n    next();\n  },\n  async onActivity(data) {\n    console.log('Authorization activity:', data);\n    // Implement your logging logic here\n  }\n});\n\n// authMiddleware checks if the user has permission to access the specified resources and actions\nconst authMiddleware = (resources, actions) =\u003e {\n  const role = 'user'; // Assuming the user is authenticated and has the 'user' role\n  return roleManager.check({\n    resources,\n    actions,\n    role,\n    strict: true\n  });\n};\n\n\napp.get('/posts', \n  authMiddleware('posts', ['read', 'list']),\n  (req, res) =\u003e {\n    res.json({ message: 'Posts retrieved successfully' });\n  }\n);\n\napp.listen(3000, () =\u003e console.log('Server running on http://localhost:3000'));\n```\n\nThis setup checks if a 'user' role has permission to read and list posts before allowing access to the '/posts' route.\n\n## Framework Support\n\niamjs provides dedicated packages for popular frameworks:\n\n- **Express.js**: `@iamjs/express`\n- **Koa**: `@iamjs/koa`\n- **Next.js**: `@iamjs/next`\n- **React**: `@iamjs/react`\n\nEach package offers framework-specific features while maintaining consistent core functionality.\n\n## Advanced Usage\n\n### Dynamic Role Construction\n\nFor scenarios where roles need to be constructed dynamically (e.g., based on database data):\n\n```typescript\nconst roleManager = new ExpressRoleManager({\n  schema,\n  // ... other options\n});\n\napp.get('/dynamic-resource',\n  roleManager.check({\n    resources: 'dynamicResource',\n    actions: ['read'],\n    construct: true,\n    data: async (req) =\u003e {\n      // Fetch user permissions from database or JWT\n      const userPermissions = await getUserPermissions(req.user.id);\n      return userPermissions;\n    }\n  }),\n  (req, res) =\u003e {\n    res.json({ message: 'Access granted to dynamic resource' });\n  }\n);\n```\n\nThis approach allows for flexible, user-specific permissions that can be determined at runtime.\n\n## Best Practices\n\n1. **Granular Permissions**: Define permissions at a granular level for fine-tuned access control.\n2. **Use Environment Variables**: Store role configurations in environment variables for easy management across different environments.\n3. **Regular Audits**: Periodically review and update your role definitions to ensure they align with your application's evolving security requirements.\n4. **Implement Logging**: Utilize the `onActivity` handler to maintain an audit trail of authorization decisions.\n5. **Type Safety**: Leverage TypeScript to ensure type safety across your authorization logic.\n\n## Contributing\n\nWe welcome contributions to iamjs! Please read our [contributing guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## License\n\niamjs is released under the [MIT License](https://github.com/triyanox/iamjs/blob/main/LICENSE).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaqchase%2Fiamjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchaqchase%2Fiamjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaqchase%2Fiamjs/lists"}