optima/PERMISSIONS.md

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
company.fetch.address	View company address information (requires company.fetch as well)	src/api/companies/[id]/fetch.ts
company.fetch.many	Fetch multiple companies	src/api/companies/fetchAll.ts
company.fetch.configurations	Fetch company configurations (requires company.fetch as well)	src/api/companies/[id]/configurations.ts

Credential Permissions

Permission Node	Description	Used In
credential.create	Create a new credential	src/api/credentials/create.ts
credential.fetch	Fetch a single credential	src/api/credentials/fetch.ts
credential.fetch.many	Fetch multiple credentials	src/api/credentials/fetchByCompany.ts
credential.update	Update a credential	src/api/credentials/update.ts
credential.delete	Delete a credential	src/api/credentials/delete.ts
credential.fields.fetch	Fetch credential fields (requires credential.fetch as well)	src/api/credentials/fetchFields.ts
credential.fields.update	Update credential fields (requires credential.update as well)	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

Credential Type Permissions

Permission Node	Description	Used In
credential_type.create	Create a new credential type	src/api/credential-types/create.ts
credential_type.fetch	Fetch a single credential type	src/api/credential-types/fetch.ts
credential_type.fetch.many	Fetch multiple credential types	src/api/credential-types/fetchAll.ts
credential_type.update	Update a credential type	src/api/credential-types/update.ts
credential_type.delete	Delete a credential type	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
role.read	Fetch a single role or view role information	src/api/roles/fetch.ts
role.list	Fetch all roles	src/api/roles/fetchAll.ts	role.read
role.modify	Update role properties or manage role permissions	src/api/roles/update.ts, src/api/roles/addPermissions.ts, src/api/roles/removePermissions.ts
role.delete	Delete a role	src/api/roles/delete.ts
user.read	View users assigned to a role	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
user.write	Update user information	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
role.read	Fetch a flat list of all permission nodes	src/api/permissions/fetchNodes.ts
role.read	Fetch permission nodes by category	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) 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

// 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