{"id":16611501,"url":"https://github.com/thenamankumar/auth-policy","last_synced_at":"2025-06-23T05:36:56.871Z","repository":{"id":42889023,"uuid":"254463687","full_name":"thenamankumar/auth-policy","owner":"thenamankumar","description":"A minimal authorization policy builder to be used across application layers.","archived":false,"fork":false,"pushed_at":"2023-01-06T03:08:24.000Z","size":687,"stargazers_count":5,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-02T03:51:14.007Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thenamankumar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-09T19:44:59.000Z","updated_at":"2022-03-18T16:36:08.000Z","dependencies_parsed_at":"2023-02-05T04:32:22.761Z","dependency_job_id":null,"html_url":"https://github.com/thenamankumar/auth-policy","commit_stats":null,"previous_names":["hereisnaman/auth-policy"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenamankumar%2Fauth-policy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenamankumar%2Fauth-policy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenamankumar%2Fauth-policy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenamankumar%2Fauth-policy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thenamankumar","download_url":"https://codeload.github.com/thenamankumar/auth-policy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238729334,"owners_count":19520774,"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","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":[],"created_at":"2024-10-12T01:38:07.677Z","updated_at":"2025-02-14T15:31:37.795Z","avatar_url":"https://github.com/thenamankumar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# auth-policy\nA minimal authorization policy builder which defines if a viewer can perform an action on an entity. The Policy can be defined in a declarative manner and can be consumed at various layers of any application.\n\n## Usage\n```\nyarn add auth-policy\n```\n\n```javascript\nimport Policy from 'auth-policy'\n\n// create a new policy\nconst userPolicy = new Policy();\n\n// register concern\nuserPolicy.register('update', ({ viewer, entity: user, value }) =\u003e {\n  if(viewer.role === 'Admin') return true;\n    \n  if(viewer.id === user.id) {\n    if(value.role === 'Admin') return false;\n      \n    return true;\n  }\n    \n  return false;\n});\n\n// verify authorization\nuserPolicy.can(viewer).perform(':update').having(value).on(user);\n```\n\n## Documentation\n\n Name | Description\n------------ | -------------\nviewer| The user for whom the authorization is being verified.\naction| A string which defines the action to be performed by the viewer.\nentity| The object against which the action is to be performed.\nvalue| The value associated with the action.\n\n### Concerns\nEvery policy has multiple concerns, each of which maps to an action performed by the viewer and defines if the viewer is authorized to perfom that certain action. Concerns are added to a policy using the `register` function.\n\n```javascript\nimport Policy from 'auth-policy';\n\nconst userPolicy = new Policy();\n\n// registering a single concern\n// associated action = ':read'\nuserPolicy.register('read', ({ viewer }) =\u003e !!viewer);\n\n// registering multiple concerns with same authorization policy\n// associated actions = ':update', ':delete'\nuserPolicy.register(['update', 'delete'], ({ viewer, entity }) =\u003e \n  viewer.role === 'Admin' || viewer.id === entity.id\n);\n```\n\n### Child Policies\nAny policy can have multiple child policies which can be included using the `include` function. It is recommended to have a single root level policy and nest all the other entity level policies inside it.\n\nA policy can be included in two ways, either by passing a prebuilt instance of `Policy` or using a callback function which receives a fresh instance of `Policy` in the argument that can be used to define the concerns inside the function. Policies can be deeply nested as much as you need.\n\n```javascript\nimport Policy from 'auth-policy';\n\nconst postPolicy = new Policy();\n// associated action = ':read'\npostPolicy.register('read', ({ viewer, entity }) =\u003e \n  entity.isPublished || viewer.id === entity.publisher_id\n);\n\nconst policy = new Policy();\n\n// including a prebuilt policy\n// available actions = 'post:read'\npolicy.include('post', postPolicy);\n\n// using a callback function to define a new policy\n// accociated actions = 'user:read', 'user:email:update', 'user:phone_number:update'\npolicy.include('user', p =\u003e {\n  p.register('read', ({ viewer }) =\u003e !!viewer);\n  \n  // include another set of nested policies at once\n  p.include(['email', 'phone_number'], p =\u003e {\n    p.register('update', ({ viewer, entity: user }) =\u003e viewer.id === user.id);\n  });\n});\n```\n\n### Authorization\nOnce the policy is defined we can simply use the `can` function chain to verify the access to the viewer for a certain action.\n\n```javascript\nimport Policy from 'auth-policy';\n\nconst policy = new Policy();\n\npolicy.include('invite', p =\u003e {\n  p.register('read', () =\u003e true);\n  p.register('update', ({ viewer, entity: invite, value }) =\u003e {\n    if(viewer.id === invite.organiser_id) return true;\n      \n    if(viewer.id === invite.user_id) {\n      if(invite.status === 'Requested' \u0026\u0026 value.status === 'Accepted')\n        return false;\n      \n      return true;\n    } \n      \n    return false;\n  });\n});\n\nconst viewer = { id: 1 };\nconst organiser = { id: 2 };\nconst invite = { user_id: 1, organiser_id: 2, status: 'Requested' };\n\npolicy.can(viewer).perform('invite:read').on(invite); // true\n\nconst updatedValue = { status: 'Accepted' };\n\n/* pass value using `having` function if\n * there is any value associated with the action. */\npolicy.can(viewer).perform('invite:update').having(updatedValue).on(invite) // false\n\npolicy.can(organiser).perform('invite:update').having(updatedValue).on(invite) // true\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenamankumar%2Fauth-policy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthenamankumar%2Fauth-policy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenamankumar%2Fauth-policy/lists"}