Authorization service¶

`consortium.server.services.authorization_service` ¶

`AuthorizationService(role_permissions_json_file)` ¶

`load_role_permissions_from_path(path)` ¶

Reads, validates and returns role permission data from path.

The file must contain a JSON object whose keys are role name strings (uppercase letters, digits, and underscores) and whose values are arrays of UserPermissions string values.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Absolute path to the role permissions JSON file to load.	required

Returns:

Type	Description
`dict[str, list[str]]`	The validated role-to-permissions mapping.

Raises:

Type	Description
`RolePermissionsFileSystemError`	If `path` cannot be opened or read, for example it does not exist, read permission is denied, or the path points to a directory.
`RolePermissionsFileEncodingError`	If the file's contents cannot be decoded as UTF-8 text.
`RolePermissionsFileJSONError`	If the file is not valid JSON.
`RolePermissionsFileSchemaError`	If the file does not conform to the expected JSON schema.
`RolePermissionsFilePermissionValueError`	If any permission string is not a recognised UserPermissions value.

`save_role_permissions_to_path(path, role_permissions)` ¶

Serialises role_permissions to JSON and writes it to path.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Absolute path to write the role permissions JSON file to.	required
`role_permissions`	`dict[str, list[str]]`	Mapping of role name -> list of permission strings to persist.	required

Raises:

Type	Description
`RolePermissionsFileSystemError`	If `path` cannot be opened or written to, for example the parent directory does not exist, write permission is denied, or the disk is full.

`load_server_role_permissions()` ¶

Loads role permissions from the server's default role_permissions.json file.

Calls load_role_permissions_from_path with the path supplied at construction time and replaces the current in-memory role permissions with the loaded data.

Raises:

Type	Description
`RolePermissionsFileSystemError`	Propagated from the base loader.
`RolePermissionsFileEncodingError`	Propagated from the base loader.
`RolePermissionsFileJSONError`	Propagated from the base loader.
`RolePermissionsFileSchemaError`	Propagated from the base loader.
`RolePermissionsFilePermissionValueError`	Propagated from the base loader.

`save_server_role_permissions()` ¶

Persists the current in-memory role permissions to the server's default file.

Calls save_role_permissions_to_path with the path supplied at construction time and the current in-memory state.

Raises:

Type	Description
`RolePermissionsFileSystemError`	Propagated from the base writer.

`get_all_roles()` ¶

Returns a copy of the current role-to-permissions mapping.

Returns:

Type	Description
`dict[str, set[str]]`	Mapping of role name -> set of permission strings.

`get_role_permissions(role)` ¶

Returns the set of permissions assigned to role.

Parameters:

Name	Type	Description	Default
`role`	`str`	The name of the role to look up.	required

Returns:

Type	Description
`set[str]`	The permissions assigned to the role.

Raises:

Type	Description
`RoleNotFoundError`	If no role with the given name exists.

`create_role(role, permissions=None)` ¶

Creates a new role with an optional initial set of permissions.

Parameters:

Name	Type	Description	Default
`role`	`str`	The name of the new role. No format validation is performed here, any string is accepted. Note that `_ROLE_PERMISSIONS_JSON_SCHEMA` requires role names to match `^[A-Z][A-Z0-9_]*$` when a role permissions file is loaded (see `load_role_permissions_from_path`), so a role created here whose name violates that pattern will fail to load back the next time `load_server_role_permissions` is called.	required
`permissions`	`set[str] \| None`	Initial permissions to assign. When `None`, the role starts with no permissions.	`None`

Raises:

Type	Description
`RoleAlreadyExistsError`	If a role with the given name already exists.

`delete_role(role)` ¶

Removes the specified role and all of its permissions.

Parameters:

Name	Type	Description	Default
`role`	`str`	The name of the role to delete.	required

Raises:

Type	Description
`RoleNotFoundError`	If no role with the given name exists.

`update_role_permissions(role, permissions)` ¶

Replaces all permissions for role with permissions.

Parameters:

Name	Type	Description	Default
`role`	`str`	The name of the role to update.	required
`permissions`	`set[str]`	The complete new set of permissions for the role.	required

Raises:

Type	Description
`RoleNotFoundError`	If no role with the given name exists.

`add_permission_to_role(role, permission)` ¶

Adds a single permission to an existing role.

Parameters:

Name	Type	Description	Default
`role`	`str`	The name of the role to modify.	required
`permission`	`str`	The permission string to add.	required

Raises:

Type	Description
`RoleNotFoundError`	If no role with the given name exists.
`PermissionAlreadyInRoleError`	If the permission is already assigned to the role.

`remove_permission_from_role(role, permission)` ¶

Removes a single permission from an existing role.

Parameters:

Name	Type	Description	Default
`role`	`str`	The name of the role to modify.	required
`permission`	`str`	The permission string to remove.	required

Raises:

Type	Description
`RoleNotFoundError`	If no role with the given name exists.
`PermissionNotInRoleError`	If the permission is not assigned to the role.

`has_permission(role, permission)` ¶

Returns whether a role has a particular permission.

Returns False (rather than raising) when the role does not exist, to keep the FastAPI dependency path simple.

Parameters:

Name	Type	Description	Default
`role`	`str`	The role name to check (accepts raw strings and StrEnum values).	required
`permission`	`str`	The permission string to test for.	required

Returns:

Type	Description
`bool`	`True` if the role exists and holds the permission.

Authorization service¶

consortium.server.services.authorization_service ¶