tba-app-backend-platform-administration 0.4.0.dev2__tar.gz

tba_app_backend_platform_administration-0.4.0.dev2/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: tba-app-backend-platform-administration
+Version: 0.4.0.dev2
+Summary: Platform owner and operator control-plane backend application for TBA.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10,<3.15
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pydantic (==2.12.5)
+Requires-Dist: tba-app-backend-core (==0.4.0.dev2)
+Requires-Dist: tba-auth (==0.4.0.dev2)
+Requires-Dist: tba-contracts-identity (==0.4.0.dev2)
+Requires-Dist: tba-router-administration-gate (==0.4.0.dev2)
+Requires-Dist: tba-server-identity (==0.4.0.dev2)
+Requires-Dist: tigrbl (==0.4.5.dev8)
+Project-URL: Homepage, https://github.com/tigrbl/tigrbl_auth
+Project-URL: Repository, https://github.com/tigrbl/tigrbl_auth
+Project-URL: Source, https://github.com/tigrbl/tigrbl_auth/tree/master/pkgs/90-backend-apps/tba-app-backend-platform-administration
+Description-Content-Type: text/markdown
+
+# tba-app-backend-platform-administration
+
+Platform-scoped tenant lifecycle and authority-assignment API front door.
+
+## Surface
+
+| Property | Value |
+| --- | --- |
+| Product surface | `platform-admin-app` |
+
+The backend app owns HTTP schemas and routes only. Tenant, realm, and identity
+administration are invoked through request-scoped layer-40 capabilities composed
+by `tba-server-identity`; durable table operations and secret hashing remain
+in the layer-60 runtime adapters and their lower-layer providers.
+| Intended UIX | `@tba/ui-platform-administration` |
+| Exposes | Tenant lifecycle, platform authority assignment, admin identity lookup, audit/session/profile RPC |
+| Excludes | Public login/consent pages, tenant self-service-only workflows, developer app registration surface |
+
+## Entrypoint
+
+```python
+from tba_app_backend_platform_administration import app, build_app
+```
+
+## Local dev deployment
+
+Run the isolated platform control-plane front door on port `8015`:
+
+```bash
+docker compose -f docker/docker-compose.platform-admin-app.yml up -d --build
+```
+
+The dev API key defaults to `dev-platform-admin-key`.
+
+Useful endpoints:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `/openapi.json` | Platform-admin REST/control-plane contract. |
+| `/openrpc.json` | Platform-admin JSON-RPC method contract. |
+| `/rpc` | API-key-protected JSON-RPC dispatch. |
+| `/tenant` | API-key-protected platform tenant lifecycle resource. |
+

tba_app_backend_platform_administration-0.4.0.dev2/README.md

@@ -0,0 +1,42 @@
+# tba-app-backend-platform-administration
+
+Platform-scoped tenant lifecycle and authority-assignment API front door.
+
+## Surface
+
+| Property | Value |
+| --- | --- |
+| Product surface | `platform-admin-app` |
+
+The backend app owns HTTP schemas and routes only. Tenant, realm, and identity
+administration are invoked through request-scoped layer-40 capabilities composed
+by `tba-server-identity`; durable table operations and secret hashing remain
+in the layer-60 runtime adapters and their lower-layer providers.
+| Intended UIX | `@tba/ui-platform-administration` |
+| Exposes | Tenant lifecycle, platform authority assignment, admin identity lookup, audit/session/profile RPC |
+| Excludes | Public login/consent pages, tenant self-service-only workflows, developer app registration surface |
+
+## Entrypoint
+
+```python
+from tba_app_backend_platform_administration import app, build_app
+```
+
+## Local dev deployment
+
+Run the isolated platform control-plane front door on port `8015`:
+
+```bash
+docker compose -f docker/docker-compose.platform-admin-app.yml up -d --build
+```
+
+The dev API key defaults to `dev-platform-admin-key`.
+
+Useful endpoints:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `/openapi.json` | Platform-admin REST/control-plane contract. |
+| `/openrpc.json` | Platform-admin JSON-RPC method contract. |
+| `/rpc` | API-key-protected JSON-RPC dispatch. |
+| `/tenant` | API-key-protected platform tenant lifecycle resource. |

tba_app_backend_platform_administration-0.4.0.dev2/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "tba-app-backend-platform-administration"
+version = "0.4.0.dev2"
+description = "Platform owner and operator control-plane backend application for TBA."
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "Apache-2.0"
+dependencies = [
+    "pydantic==2.12.5",
+    "tigrbl==0.4.5.dev8",
+    "tba-auth==0.4.0.dev2",
+    "tba-app-backend-core==0.4.0.dev2",
+    "tba-router-administration-gate==0.4.0.dev2",
+    "tba-contracts-identity==0.4.0.dev2",
+    "tba-server-identity==0.4.0.dev2",
+]
+
+[project.urls]
+Homepage = "https://github.com/tigrbl/tigrbl_auth"
+Repository = "https://github.com/tigrbl/tigrbl_auth"
+Source = "https://github.com/tigrbl/tigrbl_auth/tree/master/pkgs/90-backend-apps/tba-app-backend-platform-administration"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "tba_app_backend_platform_administration", from = "src" }]

tba_app_backend_platform_administration-0.4.0.dev2/src/tba_app_backend_platform_administration/__init__.py

@@ -0,0 +1,33 @@
+"""Platform admin backend application package for TBA."""
+
+from __future__ import annotations
+
+from .app import PRODUCT_SURFACE, app, build_app
+from .contract import (
+    PLATFORM_ADMIN_BACKEND_APP_CONTRACT,
+    PlatformAdminBackendAppContract,
+)
+from .identities import (
+    AdminIdentityOut,
+    AdminIdentityProvisionIn,
+    AdminIdentityUpdateIn,
+)
+from .realms import AdminRealmOut, AdminRealmProvisionIn, AdminRealmUpdateIn
+from .tenants import AdminTenantOut, AdminTenantProvisionIn, AdminTenantUpdateIn
+
+__all__ = [
+    "AdminIdentityOut",
+    "AdminIdentityProvisionIn",
+    "AdminIdentityUpdateIn",
+    "AdminRealmOut",
+    "AdminRealmProvisionIn",
+    "AdminRealmUpdateIn",
+    "AdminTenantOut",
+    "AdminTenantProvisionIn",
+    "AdminTenantUpdateIn",
+    "PRODUCT_SURFACE",
+    "PLATFORM_ADMIN_BACKEND_APP_CONTRACT",
+    "PlatformAdminBackendAppContract",
+    "app",
+    "build_app",
+]

tba_app_backend_platform_administration-0.4.0.dev2/src/tba_app_backend_platform_administration/app.py

@@ -0,0 +1,138 @@
+"""ASGI entrypoint for the platform admin TBA backend application."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+from tba_app_backend_core import build_product_app
+from tba_app_backend_platform_administration.contract import (
+    PLATFORM_ADMIN_BACKEND_APP_CONTRACT,
+)
+from tba_auth.runtime import LazyASGIApplication
+from tba_app_backend_platform_administration.identities import router as identity_router
+from tba_app_backend_platform_administration.realms import router as realm_router
+from tba_app_backend_platform_administration.tenants import router as tenant_router
+
+if TYPE_CHECKING:
+    from tigrbl import TigrblApp
+
+PRODUCT_SURFACE = "platform-admin-app"
+DEFAULT_CORS_ORIGINS = ("http://localhost:3011", "http://127.0.0.1:3011")
+
+
+class PlatformAdminCors:
+    """Small ASGI CORS wrapper for the standalone platform admin UIX demo."""
+
+    def __init__(
+        self, app: Any, origins: tuple[str, ...] = DEFAULT_CORS_ORIGINS
+    ) -> None:
+        self.app = app
+        self.origins = origins
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.app, name)
+
+    async def __call__(
+        self,
+        scope: dict[str, Any],
+        receive: Callable[[], Awaitable[dict[str, Any]]],
+        send: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = {
+            key.decode("latin-1").lower(): value.decode("latin-1")
+            for key, value in scope.get("headers", [])
+        }
+        origin = headers.get("origin")
+        allowed_origin = origin if origin in self.origins else None
+
+        if str(scope.get("method", "")).upper() == "OPTIONS" and allowed_origin:
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 204,
+                    "headers": self._cors_headers(allowed_origin)
+                    + [
+                        (
+                            b"access-control-allow-methods",
+                            b"GET,POST,PATCH,DELETE,OPTIONS",
+                        ),
+                        (
+                            b"access-control-allow-headers",
+                            headers.get(
+                                "access-control-request-headers",
+                                "content-type,authorization,x-api-key",
+                            ).encode("latin-1"),
+                        ),
+                        (b"content-length", b"0"),
+                    ],
+                }
+            )
+            await send({"type": "http.response.body", "body": b""})
+            return
+
+        async def cors_send(message: dict[str, Any]) -> None:
+            if message.get("type") == "http.response.start" and allowed_origin:
+                message = dict(message)
+                response_headers = list(message.get("headers", []))
+                response_headers.extend(self._cors_headers(allowed_origin))
+                message["headers"] = response_headers
+            await send(message)
+
+        await self.app(scope, receive, cors_send)
+
+    @staticmethod
+    def _cors_headers(origin: str) -> list[tuple[bytes, bytes]]:
+        return [
+            (b"access-control-allow-origin", origin.encode("latin-1")),
+            (b"access-control-allow-credentials", b"true"),
+            (b"vary", b"Origin"),
+        ]
+
+
+def _default_settings() -> object:
+    from tba_auth.config.settings import Settings
+
+    settings = Settings()
+    env_overrides = {
+        "issuer": os.environ.get("AUTHN_ISSUER"),
+        "protected_resource_identifier": os.environ.get(
+            "TBA_AUTH_PROTECTED_RESOURCE_IDENTIFIER"
+        ),
+        "deployment_profile": os.environ.get("TBA_AUTH_PROFILE"),
+        "require_tls": os.environ.get("TBA_AUTH_REQUIRE_TLS"),
+        "admin_api_key": os.environ.get("TBA_AUTH_ADMIN_API_KEY"),
+        "admin_api_key_dir": os.environ.get("TBA_AUTH_ADMIN_API_KEY_DIR"),
+    }
+    for name, value in env_overrides.items():
+        if value in {None, ""}:
+            continue
+        current = getattr(settings, name, None)
+        if isinstance(current, bool):
+            value = str(value).lower() in {"1", "true", "yes", "on"}
+        setattr(settings, name, value)
+    return settings
+
+
+def build_app(settings_obj: object | None = None) -> "TigrblApp":
+    if settings_obj is None:
+        settings_obj = _default_settings()
+    app = build_product_app(
+        PRODUCT_SURFACE, settings_obj, contract=PLATFORM_ADMIN_BACKEND_APP_CONTRACT
+    )
+    app.include_router(tenant_router)
+    app.include_router(realm_router)
+    app.include_router(identity_router)
+    app.admin_path_prefixes = tuple(
+        dict.fromkeys((*app.admin_path_prefixes, "/admin/identities"))
+    )
+    return PlatformAdminCors(app)
+
+
+app = LazyASGIApplication(build_app)
+
+__all__ = ["PRODUCT_SURFACE", "app", "build_app"]

tba_app_backend_platform_administration-0.4.0.dev2/src/tba_app_backend_platform_administration/contract.py

@@ -0,0 +1,82 @@
+"""Platform-admin backend-app contract for TBA."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class PlatformAdminBackendAppContract:
+    """Machine-readable boundary for the platform control-plane backend app."""
+
+    product_surface: str
+    intended_uix: str
+    admin_resources: tuple[str, ...]
+    admin_rest_groups: tuple[str, ...]
+    forbidden_route_prefixes: tuple[str, ...]
+    forbidden_exact_routes: tuple[str, ...]
+    consumed_packages: tuple[str, ...]
+    mounted_router_packages: tuple[str, ...]
+    app_local_route_groups: tuple[str, ...]
+
+
+PLATFORM_ADMIN_BACKEND_APP_CONTRACT = PlatformAdminBackendAppContract(
+    product_surface="platform-admin-app",
+    intended_uix="@tba/ui-platform-administration",
+    admin_resources=(
+        "Realm",
+        "Tenant",
+        "User",
+        "AuditEvent",
+        "CryptoKey",
+        "CryptoKeyVersion",
+        "PrincipalKeyBinding",
+        "KeyEnvelope",
+        "KeyAttestationEvidence",
+        "KeyRotationEvent",
+    ),
+    admin_rest_groups=("admin_auth", "admin_realms", "admin_identities"),
+    forbidden_route_prefixes=(
+        "/client",
+        "/clientregistration",
+        "/consent",
+        "/serviceidentity",
+        "/credentialservicekey",
+        "/credentialapikey",
+        "/tokenrecord",
+        "/revokedtoken",
+        "/authsession",
+        "/tenant",
+        "/user",
+    ),
+    forbidden_exact_routes=(
+        "/login",
+        "/authorize",
+        "/token",
+        "/register",
+        "/logout",
+        "/revoke",
+        "/userinfo",
+        "/introspect",
+        "/rpc",
+        "/openrpc.json",
+        "/.well-known/jwks.json",
+        "/.well-known/openid-configuration",
+    ),
+    consumed_packages=(
+        "tba-auth",
+        "tba-server-identity",
+        "tba-runtime-identity",
+        "tba-runtime-identity-administration",
+        "tba-concrete-identity-principals",
+        "tba-runtime-authorization-policy",
+    ),
+    mounted_router_packages=("tba-router-administration-gate",),
+    app_local_route_groups=(
+        "realms",
+        "tenants",
+        "identities",
+    ),
+)
+
+__all__ = ["PLATFORM_ADMIN_BACKEND_APP_CONTRACT", "PlatformAdminBackendAppContract"]

tba_app_backend_platform_administration-0.4.0.dev2/src/tba_app_backend_platform_administration/identities.py

@@ -0,0 +1,213 @@
+"""Platform identity-administration HTTP routes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, constr
+from tigrbl import TigrblRouter
+from tigrbl.requests import Request
+from tigrbl.runtime.status import HTTPException
+from tigrbl.security import Depends
+from tba_contracts_identity.admin_identities import (
+    AdminIdentity,
+    AdminIdentityCreate,
+    AdminIdentityUpdate,
+    IdentityAdministrationConflictError,
+    IdentityAdministrationNotFoundError,
+    IdentityAdministrationPolicyError,
+    IdentityAdministrationValidationError,
+)
+from tba_contracts_identity.admin_tenants import (
+    TenantAdministratorAuthenticationError,
+)
+from tba_server_identity.platform_identity_administration import (
+    get_db,
+    identity_administration_for_request,
+    require_identity_administrator,
+)
+from tba_router_administration_gate import ADMIN_OPENAPI_SECURITY_DEPENDENCIES
+
+
+_email = constr(strip_whitespace=True, min_length=3, max_length=120)
+_password = constr(min_length=8, max_length=256)
+_username = constr(strip_whitespace=True, min_length=3, max_length=80)
+
+
+class AdminIdentityOut(BaseModel):
+    id: str
+    tenant_id: str
+    username: str
+    email: str
+    is_active: bool = True
+    is_admin: bool = False
+    is_superuser: bool = False
+    must_change_password: bool = False
+    roles: list[str] = Field(default_factory=list)
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class AdminIdentityProvisionIn(BaseModel):
+    tenant_id: str
+    username: _username
+    email: _email
+    password: _password
+    is_admin: bool = False
+    is_superuser: bool = False
+    must_change_password: bool = True
+
+
+class AdminIdentityUpdateIn(BaseModel):
+    username: _username | None = None
+    email: _email | None = None
+    password: _password | None = None
+    is_active: bool | None = None
+    is_admin: bool | None = None
+    is_superuser: bool | None = None
+    must_change_password: bool | None = None
+
+
+def _identity_payload(row: AdminIdentity) -> AdminIdentityOut:
+    return AdminIdentityOut(
+        id=row.identity_id,
+        tenant_id=row.tenant_id,
+        username=row.username,
+        email=row.email,
+        is_active=row.is_active,
+        is_admin=row.is_admin,
+        is_superuser=row.is_superuser,
+        must_change_password=row.must_change_password,
+        roles=list(row.roles),
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+async def _invoke(
+    request: Request,
+    db: Any,
+    operation: str,
+    *args: object,
+) -> object:
+    try:
+        actor = await require_identity_administrator(request, db)
+        capability = identity_administration_for_request(request, db)
+        return (await capability.call(operation, actor, *args)).value
+    except TenantAdministratorAuthenticationError as exc:
+        raise HTTPException(401, str(exc)) from exc
+    except IdentityAdministrationPolicyError as exc:
+        raise HTTPException(403, str(exc)) from exc
+    except IdentityAdministrationNotFoundError as exc:
+        raise HTTPException(404, str(exc)) from exc
+    except IdentityAdministrationConflictError as exc:
+        raise HTTPException(409, str(exc)) from exc
+    except IdentityAdministrationValidationError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+router = TigrblRouter()
+
+
+@router.route(
+    "/admin/identities",
+    methods=["GET"],
+    response_model=list[AdminIdentityOut],
+    dependencies=list(ADMIN_OPENAPI_SECURITY_DEPENDENCIES),
+)
+async def admin_list_identities(
+    request: Request,
+    tenant_id: str | None = None,
+    db: Any = Depends(get_db),
+) -> list[AdminIdentityOut]:
+    rows = await _invoke(request, db, "list_identities", tenant_id)
+    return [_identity_payload(row) for row in rows]
+
+
+@router.route(
+    "/admin/identities",
+    methods=["POST"],
+    response_model=AdminIdentityOut,
+    dependencies=list(ADMIN_OPENAPI_SECURITY_DEPENDENCIES),
+)
+async def admin_create_identity(
+    request: Request,
+    payload: AdminIdentityProvisionIn | None = None,
+    db: Any = Depends(get_db),
+) -> AdminIdentityOut:
+    if payload is None:
+        payload = AdminIdentityProvisionIn.model_validate(await request.json() or {})
+    row = await _invoke(
+        request,
+        db,
+        "create_identity",
+        AdminIdentityCreate(
+            tenant_id=payload.tenant_id,
+            username=payload.username,
+            email=str(payload.email),
+            password=payload.password,
+            is_admin=payload.is_admin,
+            is_superuser=payload.is_superuser,
+            must_change_password=payload.must_change_password,
+        ),
+    )
+    return _identity_payload(row)
+
+
+@router.route(
+    "/admin/identities/{user_id}",
+    methods=["PATCH"],
+    response_model=AdminIdentityOut,
+    dependencies=list(ADMIN_OPENAPI_SECURITY_DEPENDENCIES),
+)
+async def admin_update_identity(
+    request: Request,
+    user_id: str,
+    payload: AdminIdentityUpdateIn | None = None,
+    db: Any = Depends(get_db),
+) -> AdminIdentityOut:
+    if payload is None:
+        payload = AdminIdentityUpdateIn.model_validate(await request.json() or {})
+    row = await _invoke(
+        request,
+        db,
+        "update_identity",
+        user_id,
+        AdminIdentityUpdate(
+            username=payload.username,
+            email=str(payload.email) if payload.email is not None else None,
+            password=payload.password,
+            is_active=payload.is_active,
+            is_admin=payload.is_admin,
+            is_superuser=payload.is_superuser,
+            must_change_password=payload.must_change_password,
+        ),
+    )
+    return _identity_payload(row)
+
+
+@router.route(
+    "/admin/identities/{user_id}",
+    methods=["DELETE"],
+    response_model=AdminIdentityOut,
+    dependencies=list(ADMIN_OPENAPI_SECURITY_DEPENDENCIES),
+)
+async def admin_delete_identity(
+    request: Request,
+    user_id: str,
+    db: Any = Depends(get_db),
+) -> AdminIdentityOut:
+    row = await _invoke(request, db, "delete_identity", user_id)
+    return _identity_payload(row)
+
+
+__all__ = [
+    "AdminIdentityOut",
+    "AdminIdentityProvisionIn",
+    "AdminIdentityUpdateIn",
+    "admin_create_identity",
+    "admin_delete_identity",
+    "admin_list_identities",
+    "admin_update_identity",
+    "router",
+]

tba_app_backend_platform_administration-0.4.0.dev2/src/tba_app_backend_platform_administration/realms.py

@@ -0,0 +1,267 @@
+"""Platform realm-administration HTTP routes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, constr
+from tigrbl import TigrblRouter
+from tigrbl.requests import Request
+from tigrbl.runtime.status import HTTPException
+from tigrbl.security import Depends
+from tba_router_administration_gate import ADMIN_OPENAPI_SECURITY_DEPENDENCIES
+from tba_contracts_identity.admin_realms import (
+    AdminRealm,
+    AdminRealmCreate,
+    AdminRealmUpdate,
+    RealmAdministrationConflictError,
+    RealmAdministrationNotFoundError,
+    RealmAdministrationValidationError,
+)
+from tba_contracts_identity.admin_tenants import (
+    AdminTenantCreate,
+    TenantAdministrationConflictError,
+    TenantAdministrationNotFoundError,
+    TenantAdministrationPolicyError,
+    TenantAdministrationValidationError,
+    TenantAdministratorAuthenticationError,
+)
+from tba_server_identity.platform_realm_administration import (
+    get_db,
+    realm_administration_for_request,
+    require_realm_administrator,
+)
+
+from .tenants import AdminTenantOut, AdminTenantProvisionIn, tenant_payload
+
+
+_description = constr(strip_whitespace=True, max_length=255)
+_issuer_path_value = constr(strip_whitespace=True, max_length=255)
+_name = constr(strip_whitespace=True, min_length=1, max_length=120)
+_slug = constr(strip_whitespace=True, min_length=3, max_length=120)
+_SECURITY = list(ADMIN_OPENAPI_SECURITY_DEPENDENCIES)
+
+
+class AdminRealmOut(BaseModel):
+    id: str
+    slug: str
+    name: str
+    issuer_path: str = ""
+    description: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class AdminRealmProvisionIn(BaseModel):
+    slug: _slug
+    name: _name
+    issuer_path: _issuer_path_value | None = None
+    description: _description | None = None
+
+
+class AdminRealmUpdateIn(BaseModel):
+    slug: _slug | None = None
+    name: _name | None = None
+    issuer_path: _issuer_path_value | None = None
+    description: _description | None = None
+
+
+def _realm_payload(row: AdminRealm) -> AdminRealmOut:
+    return AdminRealmOut(
+        id=row.realm_id,
+        slug=row.slug,
+        name=row.name,
+        issuer_path=row.issuer_path,
+        description=row.description,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+async def _invoke(
+    request: Request,
+    db: Any,
+    operation: str,
+    *args: object,
+) -> object:
+    try:
+        actor = await require_realm_administrator(request, db)
+        capability = realm_administration_for_request(request, db)
+        return (await capability.call(operation, actor, *args)).value
+    except TenantAdministratorAuthenticationError as exc:
+        raise HTTPException(401, str(exc)) from exc
+    except TenantAdministrationPolicyError as exc:
+        raise HTTPException(403, str(exc)) from exc
+    except (RealmAdministrationNotFoundError, TenantAdministrationNotFoundError) as exc:
+        raise HTTPException(404, str(exc)) from exc
+    except (RealmAdministrationConflictError, TenantAdministrationConflictError) as exc:
+        raise HTTPException(409, str(exc)) from exc
+    except (
+        RealmAdministrationValidationError,
+        TenantAdministrationValidationError,
+    ) as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+router = TigrblRouter()
+
+
+@router.route(
+    "/admin/realm",
+    methods=["GET"],
+    response_model=list[AdminRealmOut],
+    dependencies=_SECURITY,
+)
+async def admin_list_realms(
+    request: Request,
+    db: Any = Depends(get_db),
+) -> list[AdminRealmOut]:
+    rows = await _invoke(request, db, "list_realms")
+    return [_realm_payload(row) for row in rows]
+
+
+@router.route(
+    "/admin/realm",
+    methods=["POST"],
+    response_model=AdminRealmOut,
+    dependencies=_SECURITY,
+)
+async def admin_create_realm(
+    request: Request,
+    payload: AdminRealmProvisionIn | None = None,
+    db: Any = Depends(get_db),
+) -> AdminRealmOut:
+    if payload is None:
+        payload = AdminRealmProvisionIn.model_validate(await request.json() or {})
+    row = await _invoke(
+        request,
+        db,
+        "create_realm",
+        AdminRealmCreate(
+            slug=payload.slug,
+            name=payload.name,
+            issuer_path=payload.issuer_path,
+            description=payload.description,
+        ),
+    )
+    return _realm_payload(row)
+
+
+@router.route(
+    "/admin/realm/{realm_id}",
+    methods=["GET"],
+    response_model=AdminRealmOut,
+    dependencies=_SECURITY,
+)
+async def admin_get_realm(
+    request: Request,
+    realm_id: str,
+    db: Any = Depends(get_db),
+) -> AdminRealmOut:
+    row = await _invoke(request, db, "read_realm", realm_id)
+    if row is None:
+        raise HTTPException(404, "realm not found")
+    return _realm_payload(row)
+
+
+@router.route(
+    "/admin/realm/{realm_id}",
+    methods=["PATCH"],
+    response_model=AdminRealmOut,
+    dependencies=_SECURITY,
+)
+async def admin_update_realm(
+    request: Request,
+    realm_id: str,
+    payload: AdminRealmUpdateIn | None = None,
+    db: Any = Depends(get_db),
+) -> AdminRealmOut:
+    if payload is None:
+        payload = AdminRealmUpdateIn.model_validate(await request.json() or {})
+    row = await _invoke(
+        request,
+        db,
+        "update_realm",
+        realm_id,
+        AdminRealmUpdate(
+            slug=payload.slug,
+            name=payload.name,
+            issuer_path=payload.issuer_path,
+            description=payload.description,
+        ),
+    )
+    return _realm_payload(row)
+
+
+@router.route(
+    "/admin/realm/{realm_id}",
+    methods=["DELETE"],
+    response_model=AdminRealmOut,
+    dependencies=_SECURITY,
+)
+async def admin_delete_realm(
+    request: Request,
+    realm_id: str,
+    db: Any = Depends(get_db),
+) -> AdminRealmOut:
+    row = await _invoke(request, db, "delete_realm", realm_id)
+    return _realm_payload(row)
+
+
+@router.route(
+    "/admin/realm/{realm_id}/tenant",
+    methods=["GET"],
+    response_model=list[AdminTenantOut],
+    dependencies=_SECURITY,
+)
+async def admin_list_realm_tenants(
+    request: Request,
+    realm_id: str,
+    db: Any = Depends(get_db),
+) -> list[AdminTenantOut]:
+    rows = await _invoke(request, db, "list_realm_tenants", realm_id)
+    return [tenant_payload(row) for row in rows]
+
+
+@router.route(
+    "/admin/realm/{realm_id}/tenant",
+    methods=["POST"],
+    response_model=AdminTenantOut,
+    dependencies=_SECURITY,
+)
+async def admin_create_realm_tenant(
+    request: Request,
+    realm_id: str,
+    payload: AdminTenantProvisionIn | None = None,
+    db: Any = Depends(get_db),
+) -> AdminTenantOut:
+    if payload is None:
+        payload = AdminTenantProvisionIn.model_validate(await request.json() or {})
+    row = await _invoke(
+        request,
+        db,
+        "create_realm_tenant",
+        realm_id,
+        AdminTenantCreate(
+            realm_id=realm_id,
+            slug=payload.slug,
+            name=payload.name,
+            email=payload.email,
+        ),
+    )
+    return tenant_payload(row)
+
+
+__all__ = [
+    "AdminRealmOut",
+    "AdminRealmProvisionIn",
+    "AdminRealmUpdateIn",
+    "admin_create_realm",
+    "admin_create_realm_tenant",
+    "admin_delete_realm",
+    "admin_get_realm",
+    "admin_list_realm_tenants",
+    "admin_list_realms",
+    "admin_update_realm",
+    "router",
+]

tba_app_backend_platform_administration-0.4.0.dev2/src/tba_app_backend_platform_administration/tenants.py

@@ -0,0 +1,195 @@
+"""Platform tenant-administration HTTP routes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, constr
+from tigrbl import TigrblRouter
+from tigrbl.requests import Request
+from tigrbl.runtime.status import HTTPException
+from tigrbl.security import Depends
+from tba_router_administration_gate import ADMIN_OPENAPI_SECURITY_DEPENDENCIES
+from tba_contracts_identity.admin_tenants import (
+    AdminTenant,
+    AdminTenantCreate,
+    AdminTenantUpdate,
+    TenantAdministrationConflictError,
+    TenantAdministrationNotFoundError,
+    TenantAdministrationPolicyError,
+    TenantAdministrationValidationError,
+    TenantAdministratorAuthenticationError,
+)
+from tba_server_identity.platform_tenant_administration import (
+    get_db,
+    require_tenant_administrator,
+    tenant_administration_for_request,
+)
+
+
+_email = constr(strip_whitespace=True, min_length=3, max_length=120)
+_name = constr(strip_whitespace=True, min_length=1, max_length=120)
+_slug = constr(strip_whitespace=True, min_length=3, max_length=120)
+_SECURITY = list(ADMIN_OPENAPI_SECURITY_DEPENDENCIES)
+
+
+class AdminTenantOut(BaseModel):
+    id: str
+    realm_id: str | None = None
+    slug: str
+    name: str
+    email: str
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class AdminTenantProvisionIn(BaseModel):
+    realm_id: str | None = None
+    slug: _slug
+    name: _name
+    email: _email
+
+
+class AdminTenantUpdateIn(BaseModel):
+    realm_id: str | None = None
+    slug: _slug | None = None
+    name: _name | None = None
+    email: _email | None = None
+    is_active: bool | None = None
+
+
+def tenant_payload(row: AdminTenant) -> AdminTenantOut:
+    return AdminTenantOut(
+        id=row.tenant_id,
+        realm_id=row.realm_id,
+        slug=row.slug,
+        name=row.name,
+        email=row.email,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+async def _invoke(
+    request: Request,
+    db: Any,
+    operation: str,
+    *args: object,
+) -> object:
+    try:
+        actor = await require_tenant_administrator(request, db)
+        capability = tenant_administration_for_request(request, db)
+        return (await capability.call(operation, actor, *args)).value
+    except TenantAdministratorAuthenticationError as exc:
+        raise HTTPException(401, str(exc)) from exc
+    except TenantAdministrationPolicyError as exc:
+        raise HTTPException(403, str(exc)) from exc
+    except TenantAdministrationNotFoundError as exc:
+        raise HTTPException(404, str(exc)) from exc
+    except TenantAdministrationConflictError as exc:
+        raise HTTPException(409, str(exc)) from exc
+    except TenantAdministrationValidationError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+admin_router = router = TigrblRouter()
+
+
+@router.route(
+    "/admin/tenant",
+    methods=["GET"],
+    response_model=list[AdminTenantOut],
+    dependencies=_SECURITY,
+)
+async def admin_list_tenants(
+    request: Request,
+    db: Any = Depends(get_db),
+) -> list[AdminTenantOut]:
+    rows = await _invoke(request, db, "list_tenants")
+    return [tenant_payload(row) for row in rows]
+
+
+@router.route(
+    "/admin/tenant",
+    methods=["POST"],
+    response_model=AdminTenantOut,
+    dependencies=_SECURITY,
+)
+async def admin_create_tenant(
+    request: Request,
+    payload: AdminTenantProvisionIn | None = None,
+    db: Any = Depends(get_db),
+) -> AdminTenantOut:
+    if payload is None:
+        payload = AdminTenantProvisionIn.model_validate(await request.json() or {})
+    row = await _invoke(
+        request,
+        db,
+        "create_tenant",
+        AdminTenantCreate(
+            realm_id=payload.realm_id,
+            slug=payload.slug,
+            name=payload.name,
+            email=payload.email,
+        ),
+    )
+    return tenant_payload(row)
+
+
+@router.route(
+    "/admin/tenant/{tenant_id}",
+    methods=["DELETE"],
+    response_model=AdminTenantOut,
+    dependencies=_SECURITY,
+)
+async def admin_delete_tenant(
+    request: Request,
+    tenant_id: str,
+    db: Any = Depends(get_db),
+) -> AdminTenantOut:
+    row = await _invoke(request, db, "delete_tenant", tenant_id)
+    return tenant_payload(row)
+
+
+@router.route(
+    "/admin/tenant/{tenant_id}",
+    methods=["PATCH"],
+    response_model=AdminTenantOut,
+    dependencies=_SECURITY,
+)
+async def admin_update_tenant(
+    request: Request,
+    tenant_id: str,
+    payload: AdminTenantUpdateIn | None = None,
+    db: Any = Depends(get_db),
+) -> AdminTenantOut:
+    if payload is None:
+        payload = AdminTenantUpdateIn.model_validate(await request.json() or {})
+    row = await _invoke(
+        request,
+        db,
+        "update_tenant",
+        tenant_id,
+        AdminTenantUpdate(
+            realm_id=payload.realm_id,
+            slug=payload.slug,
+            name=payload.name,
+            email=payload.email,
+            is_active=payload.is_active,
+        ),
+    )
+    return tenant_payload(row)
+
+
+__all__ = [
+    "AdminTenantOut",
+    "AdminTenantProvisionIn",
+    "AdminTenantUpdateIn",
+    "admin_create_tenant",
+    "admin_delete_tenant",
+    "admin_list_tenants",
+    "admin_router",
+    "admin_update_tenant",
+    "router",
+    "tenant_payload",
+]