roles
This commit is contained in:
+148
@@ -0,0 +1,148 @@
|
||||
# Permission Nodes
|
||||
|
||||
This document lists all known permission nodes in the ttscm-api application, categorized by resource type.
|
||||
|
||||
## Permission System Overview
|
||||
|
||||
The permission system uses a dot-notation format: `resource.action[.modifier]`
|
||||
|
||||
### Special Tokens
|
||||
|
||||
The permission validator supports special tokens for flexible permission management:
|
||||
|
||||
- **Asterisk (\*)**: Matches the token and all following tokens (e.g., `credential.*` grants all credential permissions)
|
||||
- **Question Mark (?)**: Matches only the specific token (single character wildcard)
|
||||
- **Inclusive List ([a,b,c])**: Matches only the tokens in the list
|
||||
- **Exclusive List (<a,b,c>)**: Matches all tokens except those in the list
|
||||
|
||||
### Global Permissions
|
||||
|
||||
- `*` - Full access to all resources and actions (typically assigned to administrator role)
|
||||
|
||||
## Permission Nodes by Resource
|
||||
|
||||
### Company Permissions
|
||||
|
||||
| Permission Node | Description | Used In |
|
||||
| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
||||
| `company.fetch` | Fetch a single company | [src/api/companies/[id]/fetch.ts](src/api/companies/[id]/fetch.ts) |
|
||||
| `company.fetch.address` | View company address information (requires `company.fetch` as well) | [src/api/companies/[id]/fetch.ts](src/api/companies/[id]/fetch.ts) |
|
||||
| `company.fetch.many` | Fetch multiple companies | [src/api/companies/fetchAll.ts](src/api/companies/fetchAll.ts) |
|
||||
| `company.fetch.configurations` | Fetch company configurations (requires `company.fetch` as well) | [src/api/companies/[id]/configurations.ts](src/api/companies/[id]/configurations.ts) |
|
||||
|
||||
### Credential Permissions
|
||||
|
||||
| Permission Node | Description | Used In |
|
||||
| ------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
|
||||
| `credential.create` | Create a new credential | [src/api/credentials/create.ts](src/api/credentials/create.ts) |
|
||||
| `credential.fetch` | Fetch a single credential | [src/api/credentials/fetch.ts](src/api/credentials/fetch.ts) |
|
||||
| `credential.fetch.many` | Fetch multiple credentials | [src/api/credentials/fetchByCompany.ts](src/api/credentials/fetchByCompany.ts) |
|
||||
| `credential.update` | Update a credential | [src/api/credentials/update.ts](src/api/credentials/update.ts) |
|
||||
| `credential.delete` | Delete a credential | [src/api/credentials/delete.ts](src/api/credentials/delete.ts) |
|
||||
| `credential.fields.fetch` | Fetch credential fields (requires `credential.fetch` as well) | [src/api/credentials/fetchFields.ts](src/api/credentials/fetchFields.ts) |
|
||||
| `credential.fields.update` | Update credential fields (requires `credential.update` as well) | [src/api/credentials/updateFields.ts](src/api/credentials/updateFields.ts) |
|
||||
| `credential.secure_values.read` | Read secure values of a credential (requires `credential.fetch` as well) | [src/api/credentials/readSecureValues.ts](src/api/credentials/readSecureValues.ts) |
|
||||
|
||||
### Credential Type Permissions
|
||||
|
||||
| Permission Node | Description | Used In |
|
||||
| ---------------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| `credential_type.create` | Create a new credential type | [src/api/credential-types/create.ts](src/api/credential-types/create.ts) |
|
||||
| `credential_type.fetch` | Fetch a single credential type | [src/api/credential-types/fetch.ts](src/api/credential-types/fetch.ts) |
|
||||
| `credential_type.fetch.many` | Fetch multiple credential types | [src/api/credential-types/fetchAll.ts](src/api/credential-types/fetchAll.ts) |
|
||||
| `credential_type.update` | Update a credential type | [src/api/credential-types/update.ts](src/api/credential-types/update.ts) |
|
||||
| `credential_type.delete` | Delete a credential type | [src/api/credential-types/delete.ts](src/api/credential-types/delete.ts) |
|
||||
|
||||
### Role Permissions
|
||||
|
||||
| Permission Node | Description | Used In | Dependencies |
|
||||
| --------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
|
||||
| `role.create` | Create a new role | [src/api/roles/create.ts](src/api/roles/create.ts) | |
|
||||
| `role.read` | Fetch a single role or view role information | [src/api/roles/fetch.ts](src/api/roles/fetch.ts) | |
|
||||
| `role.list` | Fetch all roles | [src/api/roles/fetchAll.ts](src/api/roles/fetchAll.ts) | `role.read` |
|
||||
| `role.modify` | Update role properties or manage role permissions | [src/api/roles/update.ts](src/api/roles/update.ts), [src/api/roles/addPermissions.ts](src/api/roles/addPermissions.ts), [src/api/roles/removePermissions.ts](src/api/roles/removePermissions.ts) | |
|
||||
| `role.delete` | Delete a role | [src/api/roles/delete.ts](src/api/roles/delete.ts) | |
|
||||
| `user.read` | View users assigned to a role | [src/api/roles/getUsers.ts](src/api/roles/getUsers.ts) | `role.read` |
|
||||
|
||||
### User Permissions
|
||||
|
||||
| Permission Node | Description | Used In |
|
||||
| --------------- | ----------------------- | -------------------------------------------------------- |
|
||||
| `user.read` | Read user information | [src/api/user/@me/fetch.ts](src/api/user/@me/fetch.ts) |
|
||||
| `user.write` | Update user information | [src/api/user/@me/update.ts](src/api/user/@me/update.ts) |
|
||||
|
||||
### Permission Routes
|
||||
|
||||
Permissions required for accessing the permission node definitions API.
|
||||
|
||||
| Permission Node | Description | Used In |
|
||||
| --------------- | ------------------------------------------------ | -------------------------------------------------------------------------------- |
|
||||
| `role.read` | Fetch all permission nodes organized by category | [src/api/permissions/fetchAll.ts](src/api/permissions/fetchAll.ts) |
|
||||
| `role.read` | Fetch a flat list of all permission nodes | [src/api/permissions/fetchNodes.ts](src/api/permissions/fetchNodes.ts) |
|
||||
| `role.read` | Fetch permission nodes by category | [src/api/permissions/fetchByCategory.ts](src/api/permissions/fetchByCategory.ts) |
|
||||
|
||||
### UI Navigation Permissions
|
||||
|
||||
Permissions for controlling navigation visibility on the frontend.
|
||||
|
||||
| Permission Node | Description | Usage Pattern |
|
||||
| ---------------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| `ui.navigation.*.view` | View specific navigation sections (e.g., `ui.navigation.admin.view`) | Control which navigation menu items are displayed |
|
||||
|
||||
### Admin UI Permissions
|
||||
|
||||
Admin-specific UI permissions that control visibility and data loading for admin sub-tabs.
|
||||
|
||||
| Permission Node | Description | Usage Pattern |
|
||||
| ----------------------------- | ------------------------------------------------ | ------------------------------------------ |
|
||||
| `admin.users.view` | Show the Users tab and load user data | Show/hide users tab, allow user list fetch |
|
||||
| `admin.roles.view` | Show the Roles tab and load role data | Show/hide roles tab, allow role list fetch |
|
||||
| `admin.credential-types.view` | Show the Credential Types tab and load type data | Show/hide types tab, allow type list fetch |
|
||||
|
||||
#### Notes on UI Permissions
|
||||
|
||||
- **Client-side validation is not secure**: Always enforce permissions on the API level. UI permissions only control visibility and user experience.
|
||||
- **Combine with API permissions**: A user with an admin UI permission should also have the corresponding API permission (e.g., `role.list`) to actually load data.
|
||||
- **Use wildcards for flexibility**: Grant `ui.navigation.*.view` to allow all navigation sections.
|
||||
|
||||
## Permission Issuers
|
||||
|
||||
Permissions can be issued by different sources:
|
||||
|
||||
- `roles` - Permissions granted through role assignment
|
||||
- `user` - Permissions granted directly to a user
|
||||
- `api_key` - Permissions associated with an API key
|
||||
|
||||
## Permission Validation
|
||||
|
||||
The authorization middleware ([src/api/middleware/authorization.ts](src/api/middleware/authorization.ts)) enforces permissions by:
|
||||
|
||||
1. Extracting the authorization header (Bearer token or API Key)
|
||||
2. Validating the session/token
|
||||
3. Checking if the user has all required permissions for the route
|
||||
4. Throwing an `InsufficentPermission` error (403) if any required permission is missing
|
||||
|
||||
## Usage Example
|
||||
|
||||
```typescript
|
||||
// Require single permission
|
||||
authMiddleware({ permissions: ["credential.fetch"] })
|
||||
|
||||
// Require multiple permissions (all must be satisfied)
|
||||
authMiddleware({
|
||||
permissions: ["credential.fetch", "credential.secure_values.read"]
|
||||
})
|
||||
|
||||
// Administrator role with wildcard permission
|
||||
{
|
||||
moniker: "administrator",
|
||||
permissions: ["*"] // Grants all permissions
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Multiple permissions in a single route require **all** permissions to be satisfied (AND logic)
|
||||
- The `*` wildcard permission grants access to everything in the application
|
||||
- Permissions are signed using JWT with a private key for integrity
|
||||
- Permission validation supports pattern matching for flexible permission management
|
||||
Reference in New Issue
Block a user