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/domains/authz.md

@@ -0,0 +1,52 @@
+**Language / Язык:** [English](authz.md) | [Русский](../ru/domains/authz.md)
+
+# Authorization
+
+Role → privilege gate for REST mutate endpoints (and a decorator-style hook
+for SOAP): [`app/vsphere/security/authz.py`](../../app/vsphere/security/authz.py),
+[`platform_rest.py`](../../app/vsphere/rest/platform_rest.py).
+
+## Endpoints
+
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/api/vcenter/privilege` | Privilege catalog |
+| GET | `/api/vcenter/authorization/roles` | Role → privilege set |
+| GET/POST/DELETE | `/api/vcenter/authorization/permissions[/{permission_id}]` | Principal ↔ role ↔ entity bindings |
+| GET/POST/PATCH/DELETE | `/api/vcenter/identity/providers[/{provider}]` | LocalOS + OIDC + SAML identity-provider stand-ins |
+
+## Roles (seed)
+
+| Role | Scope |
+|---|---|
+| `Administrator` | Every privilege in the catalog |
+| `ReadOnly` | `System.Anonymous`, `System.Read`, `System.View`, `Datastore.Browse` |
+| `VirtualMachinePowerUser` | Read + power/snapshot/clone interactions |
+| `VirtualMachineAdministrator` | Power-user set + create/delete/reconfigure/tag/content-library privileges |
+
+`ROLE_PRIVILEGES` in `authz.py` defines the exact privilege sets; a
+non-exhaustive sample of gated privileges: `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`.
+
+## How gating works
+
+- `require_privilege(*needed)` is a FastAPI dependency factory: it resolves
+  the session, loads roles (from the session or `vsphere_credentials` if
+  absent), and raises HTTP 403 (`unauthorized`) if any listed privilege is
+  missing.
+- `require_read` is shorthand for `require_privilege("System.Read")`.
+- Permissions can also scope a role to a specific entity MOID
+  (`PermissionSpec(principal, role, entity_moid, propagate)`); the seed
+  scopes `readonly@vsphere.local` to the datacenter and the two VM-admin
+  principals to the VM folder.
+
+## Seeded principals
+
+See [Authentication](../authentication.md) for the four
+`@vsphere.local` principals and their roles, and
+[Seed profiles](../seed-profiles.md) for how permissions are scoped per
+profile.