Initial commit: VMware vSphere API simulator scaffold.

Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API
contracts, docs, client examples, and the unit/integration/compatibility
test suite for local client and tooling labs without a real vCenter.

docs/ru/domains/authz.md

@@ -0,0 +1,51 @@
+**Language / Язык:** [English](../../domains/authz.md) | [Русский](authz.md)
+
+# Авторизация
+
+Gate роль → privilege для мутирующих REST-эндпоинтов (и decorator-style hook
+для SOAP): [`app/vsphere/security/authz.py`](../../../app/vsphere/security/authz.py),
+[`platform_rest.py`](../../../app/vsphere/rest/platform_rest.py).
+
+## Эндпоинты
+
+| Метод | Путь | Заметки |
+|---|---|---|
+| GET | `/api/vcenter/privilege` | Каталог привилегий |
+| GET | `/api/vcenter/authorization/roles` | Role → набор privilege |
+| GET/POST/DELETE | `/api/vcenter/authorization/permissions[/{permission_id}]` | Привязки principal ↔ role ↔ entity |
+| GET/POST/PATCH/DELETE | `/api/vcenter/identity/providers[/{provider}]` | Stand-in'ы identity-provider LocalOS + OIDC + SAML |
+
+## Роли (seed)
+
+| Роль | Область |
+|---|---|
+| `Administrator` | Каждая привилегия в каталоге |
+| `ReadOnly` | `System.Anonymous`, `System.Read`, `System.View`, `Datastore.Browse` |
+| `VirtualMachinePowerUser` | Read + взаимодействия power/snapshot/clone |
+| `VirtualMachineAdministrator` | Набор power-user + привилегии create/delete/reconfigure/tag/content-library |
+
+`ROLE_PRIVILEGES` в `authz.py` задаёт точные наборы привилегий; неполный
+пример gated-привилегий: `VirtualMachine.Inventory.Create`,
+`VirtualMachine.Inventory.Delete`, `VirtualMachine.Interact.PowerOn`,
+`VirtualMachine.Config.CPUCount`, `VirtualMachine.Provisioning.Clone`,
+`Datastore.FileManagement`, `Network.Assign`,
+`InventoryService.Tagging.CreateTag`, `ContentLibrary.AddLibraryItem`,
+`Authorization.ModifyPermissions`.
+
+## Как работает gating
+
+- `require_privilege(*needed)` — фабрика зависимостей FastAPI: резолвит
+  сессию, загружает роли (из сессии или `vsphere_credentials`, если нет),
+  и поднимает HTTP 403 (`unauthorized`), если отсутствует любая из
+  перечисленных привилегий.
+- `require_read` — сокращение для `require_privilege("System.Read")`.
+- Permissions также могут ограничить роль конкретным entity MOID
+  (`PermissionSpec(principal, role, entity_moid, propagate)`); seed
+  ограничивает `readonly@vsphere.local` datacenter'ом, а двух VM-admin
+  принципалов — папкой VM.
+
+## Seeded-принципалы
+
+Четыре принципала `@vsphere.local` и их роли — в
+[Аутентификация](../authentication.md); как permissions скоупятся по
+профилю — в [Профили seed](../seed-profiles.md).