# 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