{"id":22914448,"url":"https://github.com/communitysolidserver/policy-engine","last_synced_at":"2025-05-12T13:43:53.246Z","repository":{"id":263580269,"uuid":"890838799","full_name":"CommunitySolidServer/policy-engine","owner":"CommunitySolidServer","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-07T07:16:00.000Z","size":579,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-11T15:17:34.445Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/CommunitySolidServer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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":"2024-11-19T09:16:36.000Z","updated_at":"2025-02-07T07:14:38.000Z","dependencies_parsed_at":"2024-11-19T10:46:13.736Z","dependency_job_id":"d46ca414-2644-4de3-984e-934190871fb2","html_url":"https://github.com/CommunitySolidServer/policy-engine","commit_stats":null,"previous_names":["communitysolidserver/policy-engine"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fpolicy-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fpolicy-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fpolicy-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fpolicy-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CommunitySolidServer","download_url":"https://codeload.github.com/CommunitySolidServer/policy-engine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253584658,"owners_count":21931550,"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-12-14T05:14:57.718Z","updated_at":"2025-05-12T13:43:53.204Z","avatar_url":"https://github.com/CommunitySolidServer.png","language":"TypeScript","readme":"# Solid Policy Engine\n\n[![npm version](https://img.shields.io/npm/v/%40solidlab%2Fpolicy-engine)](https://www.npmjs.com/package/@solidlab/policy-engine)\n\nThis package provides support for both [Web Access Control](https://solidproject.org/TR/2021/wac-20210711)(WAC)\nand [Access Control Policies](https://solid.github.io/authorization-panel/acp-specification/)(ACP) authorization.\n\n## Main Components\n\n### AuthorizationManager\n\nThis is the minimal interface of external functions a policy engine needs to be able to determine a result.\n\nDue to the nature of Solid, an engine needs a way to find the parent container of a resource.\nThis is done through the `getParent` function,\nwhich should return the identifier of the parent container,\nor `undefined` if the input is a root storage container.\n\nBesides that the engine also needs a way to receive the relevant authorization data for a resource.\nIn the case of WAC this would be the contents of the corresponding ACL resource.\nThe `getAuthorizationData` should return this data if it exists,\nand `undefined` otherwise.\n\nThis package does not provide an implementation of this interface as this depends on the Solid server implementation.\nIt is recommended to have some form of caching for `getAuthorizationData`.\n\n### PolicyEngine\n\nThis is the core interface for the package.\n`getPermissions` is used to determine the permissions,\nwhile `getPermissionsWithReport` does the same but also generates an RDF report indicating how the result was achieved.\nThe contents of the report depend on the type of authorization,\nas this will differ between WAC and ACP.\n\n### AclPermissionsEngine\n\nAn implementation of `PolicyEngine` that converts ACL permissions to more generic permissions.\nIt takes into account how ACL permissions have to be interpreted.\nSpecifically applies the following three rules:\n\n* `acl:Write` implies `acl:Append`.\n* To create a new resource you need `acl:Write` on the target, and `acl:Append` on the parent.\n* To delete a resource, you need `acl:Write` on the target, and `acl:Write` on the parent.\n\n## Web Access Control\n\nThese are the classes and interfaces specifically for WAC.\n\n### WacRepository / ManagedWacRepository\n\nThe `WacRepository` interface is used to determine the WAC authorization objects\nthat are relevant when determining permissions for the given target.\nThe `ManagedWacRepository` is an actual implementation that makes use of a `AuthorizationManager`\nto achieve this goal.\n\n### WacPolicyEngine\n\nThe `WacPolicyEngine` is an implementation of `PolicyEngine` for WAC authorization.\nIt requires a `WacRepository` to do the initial filtering.\nIt then uses an `AccessChecker` to determine which of these authorizations are valid\nand generates its result based on that.\n\n### Access Checker\n\nThere are several ways a WAC authorization might be valid:\nthe credentials could have a matching agent,\nthe agent could be part of the correct class,\nor the agent could be part of a matching group.\n\nFor each of those there is a separate access checker,\nand the result of these can then be combined using a `UnionAccessChecker`.\nIn practice this means you generally want to define your `AccessChecker` as follows:\n\n```ts\nconst accessChecker = new UnionAccessChecker([\n  new AgentAccessChecker(),\n  new AgentClassAccessChecker(),\n  new AgentGroupAccessChecker(),\n])\n```\n\n## Access Control Policies\n\nThese are the classes and interfaces specifically for ACP.\nThese work similarly to the WAC classes.\n\n### AcpRepository / ManagedAcpRepository\n\nThe `AcpRepository` interface is used to determine the ACP authorization objects\nthat are relevant when determining permissions for the given target.\nThe `ManagedAcpRepository` is an actual implementation that makes use of a `AuthorizationManager`\nto achieve this goal.\n\n### AcpPolicyEngine\n\nThe `AcpPolicyEngine` is an implementation of `PolicyEngine` for ACP authorization.\nIt requires a `AcpRepository` to do the initial filtering.\n\n## Example\n\nBelow is an example of how these classes can be set up and used to generate a permission report.\nThe example focuses on WAC, but would be quite similar for ACP.\n\n```ts\n// The manager is an external object, dependent on the server implementation\nasync function generateReport(\n  target: string,\n  credentials: Credentials,\n  manager: AuthorizationManager,\n  permissions?: string[]\n): Promise\u003cPermissionReport\u003e {\n  // The AccessChecker determines if WAC authorizations are valid\n  const accessChecker = new UnionAccessChecker([\n    new AgentAccessChecker(),\n    new AgentClassAccessChecker(),\n    new AgentGroupAccessChecker(),\n  ]);\n\n  // The engine needs a repository to get the authorizations\n  const wacEngine = new WacPolicyEngine(accessChecker, new ManagedWacRepository(wacManager));\n  \n  // This engine will make sure the ACL permissions get interpreted correctly\n  const engine = new AclPermissionsEngine(wacEngine, manager);\n\n  // The engine can then generate a report for the given target and credentials\n  const report = await engine.getPermissionsWithReport(target, credentials, permissions);\n}\n```\n\n## Components.js\n\nThe config folder contains [Components.js](https://github.com/LinkedSoftwareDependencies/Components.js/) configurations\nwhich can be used in your project to add the necessary authorization components.\n`acp.json` contains the necessary parts for ACP authorization,\nand `wac.json` those for WAC.\n\nurn:solidlab:policy-engine:AuthorizationManager\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommunitysolidserver%2Fpolicy-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommunitysolidserver%2Fpolicy-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommunitysolidserver%2Fpolicy-engine/lists"}