# CreatePermission

## Overview

CreatePermission defines a new permission in the system using the `resource:action` format. Permissions are the atomic unit of authorization, specifying what action can be performed on what resource. Examples include `orders:read`, `orders:write`, `users:delete`.

Permissions are assigned to roles, which are then assigned to users. This indirection simplifies access management at scale.

## Business Rules

- Permission key must follow `resource:action` format (lowercase letters, colon separator)
- Permission key must be unique across all permissions
- Description is optional but recommended for clarity
- Permission assignment to roles is handled by AssignPermissionToRole command

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Validate key format}
    B -->|Invalid| C[Return error: INVALID_PERMISSION_KEY_FORMAT]
    B -->|Valid| D{Key unique?}
    D -->|No| E[Return error: DUPLICATE_PERMISSION_KEY]
    D -->|Yes| F[Create permission record]
    F --> G[Return created permission]
```

## External Dependencies

- None

## Error Scenarios

- **INVALID_PERMISSION_KEY_FORMAT**: Key does not match `resource:action` pattern
- **DUPLICATE_PERMISSION_KEY**: Permission with the same key already exists

## Test Cases

- throws when key is empty
- throws when key format is invalid (no colon)
- throws when key format is invalid (multiple colons)
- throws when key format is invalid (empty resource)
- throws when key format is invalid (empty action)
- throws when permission key already exists
- creates permission with valid key
- creates permission with description
- passes custom fields through to insert
