{"id":23923549,"url":"https://github.com/flipbit03/cadurso","last_synced_at":"2026-01-25T01:12:05.813Z","repository":{"id":270289946,"uuid":"908798092","full_name":"flipbit03/cadurso","owner":"flipbit03","description":"Authorization framework for Python-based applications.","archived":false,"fork":false,"pushed_at":"2025-01-06T03:05:49.000Z","size":29,"stargazers_count":46,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-11T08:59:20.929Z","etag":null,"topics":["abac","authorization","python3","rbac"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/cadurso","language":"Python","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/flipbit03.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-27T02:06:23.000Z","updated_at":"2025-09-05T00:23:52.000Z","dependencies_parsed_at":"2025-09-11T07:32:23.272Z","dependency_job_id":"c79dcec4-9573-438e-a4ba-945e527b8f08","html_url":"https://github.com/flipbit03/cadurso","commit_stats":null,"previous_names":["flipbit03/cadurso"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/flipbit03/cadurso","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flipbit03%2Fcadurso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flipbit03%2Fcadurso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flipbit03%2Fcadurso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flipbit03%2Fcadurso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flipbit03","download_url":"https://codeload.github.com/flipbit03/cadurso/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flipbit03%2Fcadurso/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28740592,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T22:12:27.248Z","status":"ssl_error","status_checked_at":"2026-01-24T22:12:10.529Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","authorization","python3","rbac"],"created_at":"2025-01-05T18:01:46.213Z","updated_at":"2026-01-25T01:12:05.808Z","avatar_url":"https://github.com/flipbit03.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# 🐻Cadurso[^1]\nAuthorization framework for Python-based applications. Inspired by _[Oso](https://github.com/osohq/oso)_.\n\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cadurso?v=2)](https://pypi.org/project/cadurso/)\n[![PyPI - Version](https://img.shields.io/pypi/v/cadurso?v=2)](https://pypi.org/project/cadurso/)\n[![PyPI - Types](https://img.shields.io/pypi/types/cadurso?v=2)](https://pypi.org/project/cadurso/)\n\n## Overview\n\nCadurso is a lightweight and extensible authorization framework designed to handle access control scenarios by building and querying rules. It enables developers to define rules for actors performing actions on resources, with support for synchronous and asynchronous workflows. This library is inspired by the principles of the Oso framework, emphasizing flexibility and clarity in managing authorization.\n\n## Features\n\n- **Declarative Rule Definitions**: Define who can do what with ease. Rules are just Python functions[^2].\n- **Support for Sync and Async**: Handle both blocking and non-blocking authorization queries seamlessly. Rules can also be async.\n- **Immutable**: Prevent rule additions at runtime by freezing the authorization framework after defining rules.\n- **Error Handling**: Comprehensive exceptions for incomplete queries, operational issues, and rule definition errors.\n\n## Use Cases\n\n- Multi-tenant applications requiring fine-grained access control.\n- Implementing Role-Based Access Control, Attribute-Based Access Control or anything in between.\n\n## Core Concepts\n\nThe core concepts of a Cadurso-powered authorization system are `Actors`, `Actions`, and `Resources`. They are combined into `Rules` which can be added to a `Cadurso` instance, represent capabilities within a system.\n\nAfter defining rules, the framework can be marked as \"frozen\" to prevent further modifications, ensuring the integrity of the authorization system.\n\n### Actors\n\nan `Actor` can be any Python instance. e.g `User`, `ServiceAccount`.\n\n### Actions\n\n`Actions` are operations that `Actors` can attempt on `Resources`. They can be any hashable object.\n\nGood candidates for `Actions` are `str`, `Enum`, etc.\n\n_(But any object that implements `__hash__` and `__eq__` can be used)_\n\n### Resources\n\n`Resources` are entities that `Actors` interact with. They can be any object that needs to be protected. e.g `Document`, `Post`.\n\n### Rules\n\n`Rules` are combinations of `Actors`, `Actions`, and `Resources`. They are expressed as Python functions that return a boolean value.\n\nCadurso uses the type hints of the rule function to determine the types of the `Actor` and `Resource` arguments. The `Action` is passed as a parameter to the decorator that defines the rule.\n\nRule format:\n```python\ncadurso = Cadurso()\n\n@cadurso.add_rule(\u003cACTION\u003e)\ndef rule_definition(actor: [ACTOR TYPE], resource: [RESOURCE TYPE]) -\u003e bool:\n    # Return True or False based on the rule logic\n    ...\n```\n\n### State Freezing\n\nOnce you are finished defining rules, the framework should be \"frozen\" to prevent further modifications. This ensures the integrity of the authorization system.\n\n```python\ncadurso.freeze()\n```\n\n## Quick Start\n\n### Installation\n\n```bash\nuv add cadurso      # or\npoetry add cadurso  # or\npip install cadurso\n```\n\n### Complete Example\n\n#### Defining Rules\n```python\n# Initialize the authorization framework\nfrom cadurso import Cadurso\ncadurso = Cadurso()\n\n# Some Actors and Resources type definitions\nclass User:\n    ...\n\nclass Document:\n    ...\n\n# Some Actions\nclass DocumentPermission(Enum):\n    EDIT = auto()\n    \"\"\"Edit a document.\"\"\"\n\n    VIEW = auto()\n    \"\"\"Visualize a document.\"\"\"\n\n\n# Define your authorization rules\n@cadurso.add_rule(DocumentPermission.EDIT)\ndef owner_can_edit_own_document(actor: User, resource: Document) -\u003e bool:\n    return actor == resource.owner\n\n@cadurso.add_rule(DocumentPermission.EDIT)\ndef admin_can_edit_any_document(actor: User, _resource: Document) -\u003e bool:\n    return actor.role == Role.ADMIN\n\n@cadurso.add_rule(DocumentPermission.VIEW)\ndef owner_can_edit_own_document(actor: User, resource: Document) -\u003e bool:\n    \"\"\"Any person who can EDIT a document can also, obviously, VIEW it.\"\"\"\n    # Piggyback on the EDIT permission.\n    # This way we don't need to write VIEW rules for both owners and admins.\n    return cadurso.can(actor).do(DocumentPermission.EDIT).on(resource)\n\n# Async rules are also okay, if you need them\n@cadurso.add_rule(DocumentPermission.VIEW)\nasync def async_rule(actor: User, resource: Document) -\u003e bool:\n    return await some_other_async_check(actor, resource)\n\n\n# Freeze the rules to prevent further modifications\ncadurso.freeze()\n\n# (You are ready to query now)\n# Use your `cadurso` instance as a singleton throughout your application\n```\n\n#### Querying\n\n(Instance definitions)\n```python\n# Some Actors\njohn = User(name=\"John\", role=Role.USER)\ngunnar = User(name=\"Gunnar\", role=Role.ADMIN)\n\n# Some Resources\njohns_document = Document(owner=john)\ngunnars_document = Document(owner=gunnar)\n```\n\n(Query: Synchronous APIs)\n```python\n# `.is_allowed()` method to query permissions\ncadurso.is_allowed(john, DocumentPermission.EDIT, johns_document)   # Output: True\ncadurso.is_allowed(john, DocumentPermission.EDIT, gunnars_document) # Output: False\ncadurso.is_allowed(gunnar, DocumentPermission.EDIT, johns_document) # Output: True\n\n# Alternate querying syntax with `.can()`.\n# This is just syntactic sugar for the above.\ncadurso.can(john).do(DocumentPermission.EDIT).on(johns_document)    # Output: True\ncadurso.can(john).do(DocumentPermission.EDIT).on(gunnars_document)  # Output: False\ncadurso.can(gunnar).do(DocumentPermission.EDIT).on(johns_document)  # Output: True\n```\n\n(Query: Asynchronous APIs)\n```python\n# `.is_allowed_async()` method to query permissions asynchronously\nawait cadurso.is_allowed_async(john, DocumentPermission.EDIT, johns_document)  # Output: True\n\n# Querying permissions with `.can()` asynchronously\nawait cadurso.can(john).do(DocumentPermission.EDIT).on_async(johns_document)   # Output: True\n```\n\n#### More examples?\n\n- **ABAC** (Attribute-based Access Control) in Cadurso:\n  - Check [`/tests/akira/`](./tests/akira) for a full ABAC implementation set in the [Akira (1988 film)](https://en.wikipedia.org/wiki/Akira_(1988_film)) universe.\n\n\n- **RBAC** (Role-based Access Control) in Cadurso:\n  - The [`/tests/brazil/`](./tests/brazil) folder shows a full RBAC implementation set in the [Brazil (1985 film)](https://en.wikipedia.org/wiki/Brazil_(1985_film)) universe.\n\n\n## Contributing\nContributions are welcome! Please ensure tests are included for any new features or bug fixes. Follow the standard pull request guidelines for this repository.\n\n## License\nCadurso is licensed under the MIT License. See the LICENSE file for details.\n\n[^1]: Oso means \"bear\" in Spanish. `Cadurso` is a portmanteau of \"Cadu\" (my nickname) and \"Urso\" (\"bear\", in Portuguese) 😉\n\n[^2]: **Important:** Rules should be pure functions, and avoid mutating the actors or resources passed to them.\n      As we cannot enforce this at runtime, it is the responsibility of the developer to ensure this.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflipbit03%2Fcadurso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflipbit03%2Fcadurso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflipbit03%2Fcadurso/lists"}