Add IAM permissions and roles documentation

Document permission structure (service.resource.action), wildcard usage,
and deny-by-default security model. Explain role and permission bindings,
project-scoped access, and token introspection flow. Include API examples
for creating permissions, roles, and bindings. Add service integration
guide with Python code examples for permission checks and middleware.
Cover best practices, error handling, and important notes on caching
and access control.

Author: phantomii

docs/iam/permissions_overview.md

@@ -0,0 +1,345 @@
+## 1. Permissions Overview
+
+In the Identity and Access Management (IAM) system, a **Permission** is a core entity that defines the right to perform a specific action on a specific resource. IAM operates on a **"deny by default" model**: if a user or service does not have an explicitly granted permission for an action, that action is blocked.
+
+### 1.1. Permission Structure
+
+Each permission is represented as a string consisting of three parts separated by dots:
+
+`<service_name>.<resource_name>.<action>`
+
+*   **`<service_name>`**:
+    *   A unique identifier for a service or module in your system
+    *   Examples: `billing`, `compute`, `auth`, `storage`
+
+*   **`<resource_name>`**:
+    *   Defines the type of object an action can be performed on
+    *   Expressed in the **singular form**
+    *   Examples: `account`, `vm`, `user`, `policy`
+
+*   **`<action>`**:
+    *   Defines the operation that can be performed on the specified resource
+    *   Examples: `read`, `write`, `create`, `delete`, `activate`
+
+**Permission examples:**
+*   `billing.account.read` — view account information in the billing service
+*   `compute.vm.create` — create a new virtual machine in the compute service
+*   `auth.user.deactivate` — deactivate a user in the authentication service
+
+You can also use `*` (wildcard) in any of the three parts. It means **all** values are allowed in that part.
+
+**How `*` works by part:**
+*   `*` in the first part (`service_name`) — access for **all services**
+*   `*` in the second part (`resource_name`) — access for **all resources** in the selected service
+*   `*` in the third part (`action`) — access for **all actions** on the selected resource
+
+**Wildcard permission examples:**
+*   `*.vm.read` — allows reading `vm` in all services
+*   `compute.*.read` — allows reading any resource in the `compute` service
+*   `compute.vm.*` — allows any action on `vm` in the `compute` service
+*   `*.*.*` — full access to all services, resources, and actions
+
+### 1.2. Security Model: "Deny by Default"
+
+An important IAM philosophy is the principle of **explicit permission**:
+*   Initially, any user or service account has no access rights
+*   To perform any action, the subject must be granted the corresponding permission
+*   Services integrated with IAM must check for the required permission before executing an operation
+
+### 1.3. Permissions API Examples
+
+#### Create a Permission
+```http
+POST /v1/iam/permissions/
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "name": "compute.vm.create",
+  "description": "Permission to create a virtual machine"
+}
+```
+
+#### Response
+```json
+{
+  "uuid": "5a1b2c3d-4e5f-6789-abcd-ef0123456789",
+  "name": "compute.vm.create",
+  "description": "Permission to create a virtual machine",
+  "created_at": "2025-08-21T07:38:04.778680Z",
+  "updated_at": "2025-08-21T07:38:04.778688Z",
+  "status": "ACTIVE"
+}
+```
+
+#### Get a Permission
+```http
+GET /v1/iam/permissions/5a1b2c3d-4e5f-6789-abcd-ef0123456789
+Authorization: Bearer <token>
+```
+
+#### Filter Permissions
+```http
+GET /v1/iam/permissions/?name=compute.vm.create&status=ACTIVE
+Authorization: Bearer <token>
+```
+
+## 2. Roles
+
+A **Role** is a named collection of Permissions. While a Permission defines the right for one specific action, a Role groups these rights into logical blocks corresponding to job functions, responsibilities, or the access level of a user or service.
+
+### 2.1. Permission Binding: Linking Roles and Permissions
+
+To assign permissions to a role, the **Permission Binding** entity is used. This entity establishes a many-to-many relationship between roles and permissions.
+
+*   **One Permission** can be bound to **several different roles**
+*   **One Role** can contain **many different permissions**
+
+**Example:**
+*   The `BillingViewer` role receives the following via Permission Binding:
+    *   `billing.account.read`
+    *   `billing.invoice.read`
+*   The `BillingOperator` role receives the following via Permission Binding:
+    *   `billing.account.read`
+    *   `billing.invoice.read`
+    *   `billing.invoice.pay`
+
+### 2.2. Role Binding: Assigning Roles to Users
+
+To grant a user access, a role must be assigned to them. The **Role Binding** entity is used for this purpose. This entity establishes a many-to-many relationship between users and roles.
+
+*   **One user** can be assigned **several roles**
+*   **One role** can be assigned to **many users**
+
+### 2.3. Final Access Model
+
+The access verification process:
+1.  A **User** calls a service with a token
+2.  The **Service** calls IAM token introspection
+3.  The service gets the list of permissions available for this token from the introspection response
+4.  The **Service** checks whether the required permission exists for the requested action
+5.  If the permission is present, access is **granted**
+
+### 2.4. Roles API Examples
+
+#### Create a Role
+```http
+POST /v1/iam/roles/
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "name": "BillingOperator",
+  "description": "Billing operator with rights to manage accounts"
+}
+```
+
+#### Response
+```json
+{
+  "uuid": "6b2c3d4e-5f67-789a-bcde-f01234567890",
+  "name": "BillingOperator",
+  "description": "Billing operator with rights to manage accounts",
+  "created_at": "2025-08-21T07:38:04.779416Z",
+  "updated_at": "2025-08-21T07:38:04.779424Z",
+  "status": "ACTIVE",
+  "project_id": null
+}
+```
+
+#### Create a Permission Binding
+```http
+POST /v1/iam/permission_bindings/
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "role": "6b2c3d4e-5f67-789a-bcde-f01234567890",
+  "permission": "5a1b2c3d-4e5f-6789-abcd-ef0123456789"
+}
+```
+
+#### Create a Role Binding
+```http
+POST /v1/iam/role_bindings/
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "user": "7c3d4e5f-6789-89ab-cdef-123456789012",
+  "role": "6b2c3d4e-5f67-789a-bcde-f01234567890",
+  "project": "8d4e5f67-789a-9abc-def1-234567890123"
+}
+```
+
+#### Get User Roles
+```http
+GET /v1/iam/users/7c3d4e5f-6789-89ab-cdef-123456789012/actions/get_my_roles
+Authorization: Bearer <token>
+```
+
+### 2.5. Projects and Role/Permission Scope
+
+In IAM, roles can be assigned as:
+*   **Global** (without project, `project = null`)
+*   **Project-scoped** (via the `project` field in `Role Binding`)
+
+This directly affects the effective permission set in a token.
+
+When issuing a token, IAM determines the project from `scope`:
+*   `project:<uuid>` — token is bound to the specified project
+*   `project:default` — token is bound to the user's default project
+*   if no `project:...` segment is present in `scope`, the token is issued **without project** (`project = null`)
+
+During introspection, IAM returns permissions only in the context of the token's project.
+In other words, the effective permission set depends on which project the token is issued for.
+
+Important:
+getting a token **without project** does not automatically grant access to all projects.
+Such token includes only permissions valid in `project = null` context (global assignments) and does not include project-scoped assignments from other projects.
+
+### 2.6. How Services Should Check Permissions (Practical Template)
+
+Below is a recommended integration model for a business service with IAM.
+
+#### Basic flow
+1. Service receives a user token (`Authorization: Bearer ...`)
+2. Service calls IAM token introspection endpoint
+3. Service gets the permission list from introspection for the current token
+4. Before each protected action, service checks that required permission is present
+5. If permission is missing, service returns `403 Forbidden`
+
+#### Minimal service code structure
+```python
+class IamClient:
+    def introspect(self, token: str) -> dict:
+        # HTTP GET /v1/iam/clients/<client_uuid>/actions/introspect/invoke
+        # with Authorization: Bearer <token>
+        ...
+
+
+class AuthContext:
+    def __init__(self, token: str, introspection: dict):
+        self.token = token
+        self.introspection = introspection
+        self.permissions = {
+            p["name"] if isinstance(p, dict) else str(p)
+            for p in introspection.get("permissions", [])
+        }
+
+    def has_permission(self, permission_name: str) -> bool:
+        return permission_name in self.permissions
+
+
+class PermissionDenied(Exception):
+    pass
+```
+
+#### Guard/decorator for permission checks
+```python
+def require_permission(permission_name: str):
+    def wrapper(handler):
+        def inner(request, *args, **kwargs):
+            ctx: AuthContext = request.auth_context
+            if not ctx.has_permission(permission_name):
+                raise PermissionDenied(
+                    f"Missing required permission: {permission_name}"
+                )
+            return handler(request, *args, **kwargs)
+        return inner
+    return wrapper
+```
+
+#### Endpoint example
+```python
+@require_permission("compute.vm.create")
+def create_vm(request):
+    payload = request.json
+    # VM creation business logic
+    return {"status": "ok"}, 201
+```
+
+#### Context initialization in middleware
+```python
+def auth_middleware(request, iam_client: IamClient):
+    token = extract_bearer_token(request.headers)
+    if not token:
+        return {"error": "Unauthorized"}, 401
+
+    introspection = iam_client.introspect(token)
+    request.auth_context = AuthContext(token=token, introspection=introspection)
+    return None  # continue
+```
+
+#### Practical recommendations
+* Check permissions as close as possible to action execution point (endpoint/use-case)
+* Do not infer rights in the service — IAM must stay the source of truth
+* Only short-lived server-side cache for introspection response is acceptable; do not cache permissions on the client side
+* Log access denials with required permission and user/token context
+
+## 3. Best Practices
+
+### 3.1. Principle of Least Privilege
+Create roles that provide exactly the level of access required to perform a task, and nothing more.
+
+### 3.2. Semantic Naming
+Give roles and permissions clear names that reflect their purpose:
+*   Roles: `NetworkReadOnly`, `DatabaseSuperUser`
+*   Permissions: `compute.vm.read`, `storage.bucket.delete`
+
+### 3.3. Regular Audits
+Periodically review:
+*   Which roles are assigned to whom
+*   Which permissions are included in roles
+*   Remove unnecessary access promptly
+
+### 3.4. Using Projects for Isolation
+Use project-scoped Role Binding to isolate access between environments.
+Detailed project-context behavior is described in section **2.5**.
+
+## 4. Error Handling
+
+The following errors may occur when working with the IAM API:
+
+### 4.1. Access Error (403 Forbidden)
+```json
+{
+  "status": 403,
+  "json": {
+    "code": 403,
+    "type": "PermissionDeniedException",
+    "message": "User does not have required permission: compute.vm.create"
+  }
+}
+```
+
+### 4.2. Not Found (404 Not Found)
+```json
+{
+  "status": 404,
+  "json": {
+    "code": 404,
+    "type": "NotFoundException",
+    "message": "Role with uuid 6b2c3d4e-5f67-789a-bcde-f01234567890 not found"
+  }
+}
+```
+
+### 4.3. Bad Request (400 Bad Request)
+```json
+{
+  "status": 400,
+  "json": {
+    "code": 400,
+    "type": "ValidationErrorException",
+    "message": "Field 'name' must be between 0 and 255 characters"
+  }
+}
+```
+
+## 5. Important Notes
+
+1.  All changes to permissions and role bindings take effect immediately
+2.  Do not cache permissions on the client side; if caching is needed, use only short-lived server-side introspection cache
+3.  For service accounts, use separate roles with the minimum required permissions
+4.  Regularly update and review role assignments within the system