feat: add canonical identity administration

src/govoplan_identity/backend/manifest.py

@@ -5,20 +5,35 @@ from pathlib import Path
 from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
 from govoplan_core.core.identity import CAPABILITY_IDENTITY_DIRECTORY, CAPABILITY_IDENTITY_SEARCH
 from govoplan_core.core.module_guards import persistent_table_uninstall_guard
-from govoplan_core.core.modules import DocumentationTopic, MigrationSpec, ModuleContext, ModuleManifest, PermissionDefinition, RoleTemplate
+from govoplan_core.core.modules import (
+    DocumentationTopic,
+    FrontendModule,
+    MigrationSpec,
+    ModuleContext,
+    ModuleManifest,
+    PermissionDefinition,
+    RoleTemplate,
+    ViewSurface,
+)
 from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.db.base import Base
 from govoplan_identity.backend.db import models as identity_models  # noqa: F401 - populate metadata
 
 
-def _permission(scope: str, label: str, description: str) -> PermissionDefinition:
+def _permission(
+    scope: str,
+    label: str,
+    description: str,
+    *,
+    level: str = "tenant",
+) -> PermissionDefinition:
     module_id, resource, action = scope.split(":", 2)
     return PermissionDefinition(
         scope=scope,
         label=label,
         description=description,
         category="Identity",
-        level="tenant",
+        level=level,
         module_id=module_id,
         resource=resource,
         action=action,
@@ -27,6 +42,18 @@ def _permission(scope: str, label: str, description: str) -> PermissionDefinitio
 
 PERMISSIONS = (
     _permission("identity:identity:read", "View identities", "Search and read normalized identities and their account links."),
+    _permission(
+        "identity:identity:admin",
+        "Administer identities",
+        "Create, update, activate, and deactivate canonical system identities.",
+        level="system",
+    ),
+    _permission(
+        "identity:account_link:admin",
+        "Administer identity account links",
+        "Add, remove, and select the primary platform account for a canonical identity.",
+        level="system",
+    ),
 )
 
 ROLE_TEMPLATES = (
@@ -36,6 +63,16 @@ ROLE_TEMPLATES = (
         description="Read normalized identities and account links.",
         permissions=("identity:identity:read",),
     ),
+    RoleTemplate(
+        slug="identity_administrator",
+        name="Identity administrator",
+        description="Administer the canonical system identity directory and account links.",
+        permissions=(
+            "identity:identity:read",
+            "identity:identity:admin",
+            "identity:account_link:admin",
+        ),
+    ),
 )
 
 
@@ -61,6 +98,27 @@ manifest = ModuleManifest(
     permissions=PERMISSIONS,
     role_templates=ROLE_TEMPLATES,
     route_factory=_route_factory,
+    frontend=FrontendModule(
+        module_id="identity",
+        package_name="@govoplan/identity-webui",
+        view_surfaces=(
+            ViewSurface(
+                id="identity.admin.directory",
+                module_id="identity",
+                kind="section",
+                label="Identity directory",
+                order=30,
+            ),
+            ViewSurface(
+                id="identity.admin.account-links",
+                module_id="identity",
+                kind="section",
+                label="Identity account links",
+                parent_id="identity.admin.directory",
+                order=20,
+            ),
+        ),
+    ),
     migration_spec=MigrationSpec(
         module_id="identity",
         metadata=Base.metadata,
@@ -92,6 +150,28 @@ manifest = ModuleManifest(
             audience=("tenant_admin", "access_admin", "operator"),
             order=24,
         ),
+        DocumentationTopic(
+            id="identity.administration",
+            title="Administer the canonical identity directory",
+            summary="Manage system-scoped identities and their account links without taking over authentication or access control.",
+            body=(
+                "The Identity administration surface lists, creates, inspects, updates, deactivates, and reactivates canonical identities. These records are system-scoped; the current tenant is shown only as the acting administrative context. Account references remain opaque to Identity and one account can be linked to only one identity through this administration API. The first link becomes primary automatically. A primary link cannot be removed while another link remains: promote the replacement first. Every write and primary-account transition is recorded as a system audit event. Deactivation is reversible and does not suspend authentication, erase links, or change permissions."
+            ),
+            layer="configured",
+            documentation_types=("admin",),
+            audience=("system_admin", "identity_admin", "access_admin"),
+            order=26,
+            metadata={
+                "kind": "guide",
+                "help_contexts": ["identity.admin.directory"],
+                "prerequisites": [
+                    "The administrator has system identity administration permission.",
+                    "Account IDs are obtained from an authorized Access administration workflow.",
+                ],
+                "outcome": "Canonical identity and link state changes atomically with system-scoped audit evidence.",
+                "verification": "Reload the identity, verify its primary marker and lifecycle state, then inspect the corresponding system audit records.",
+            },
+        ),
         DocumentationTopic(
             id="identity.lifecycle",
             title="Administer identity and account-link lifecycle",