python-ddd-framework 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

python_ddd_framework/identity/management.py

@@ -18,13 +18,13 @@ from ..authorization import (
 from .contracts import (
     IDENTITY_ROLES_MANAGE,
     IDENTITY_USERS_MANAGE,
+    IdentityManagementApplicationService,
+)
+from .domain_rules import _normalize_name
+from .dtos import (
     CreateRoleCommand,
     CreateUserCommand,
     IdentityConcurrencyCommand,
-    IdentityManagementApplicationService,
-    IdentityRepository,
-    IdentityRole,
-    IdentityUser,
     RolePermissionsView,
     RoleView,
     SetPasswordCommand,
@@ -35,31 +35,34 @@ from .contracts import (
     UpdateUserCommand,
     UserRolesView,
     UserView,
-    _normalize_name,
 )
 from .errors import (
     IdentityConflictError,
     IdentityResourceNotFoundError,
 )
+from .models import IdentityRole, IdentityUser
 from .passwords import PasswordHasher
+from .stores import IdentityCredentialStore, IdentityManagementStore
 
 
 @application_service(provides=IdentityManagementApplicationService)
 class DefaultIdentityManagementApplicationService(ApplicationService):
     def __init__(
         self,
-        repository: IdentityRepository,
+        store: IdentityManagementStore,
+        credentials: IdentityCredentialStore,
         passwords: PasswordHasher,
         permissions: PermissionCatalog,
     ) -> None:
-        self._repository = repository
+        self._store = store
+        self._credentials = credentials
         self._passwords = passwords
         self._permissions = permissions
 
     @authorize(IDENTITY_USERS_MANAGE)
     async def create_user(self, command: CreateUserCommand) -> UserView:
         normalized = _normalize_name(command.username, role="username")
-        if await self._repository.find_user_by_normalized_username(normalized) is not None:
+        if await self._store.find_user_by_normalized_username(normalized) is not None:
             raise IdentityConflictError(resource="user")
         user = IdentityUser(
             user_id=uuid4(),
@@ -72,7 +75,7 @@ class DefaultIdentityManagementApplicationService(ApplicationService):
             permission_version=0,
             extra_properties=command.extra_properties,
         )
-        await self._repository.create_user(user)
+        await self._store.create_user(user)
         return UserView(
             user_id=user.user_id,
             username=user.username,
@@ -84,62 +87,62 @@ class DefaultIdentityManagementApplicationService(ApplicationService):
 
     @authorize(IDENTITY_USERS_MANAGE)
     async def get_users(self, query: PagedResultRequestDto) -> PagedResult[UserView]:
-        return await self._repository.list_users(query)
+        return await self._store.list_users(query)
 
     @authorize(IDENTITY_USERS_MANAGE)
     async def get_user(self, user_id: UUID) -> UserView:
-        return await self._repository.get_user_view(user_id)
+        return await self._store.get_user_view(user_id)
 
     @authorize(IDENTITY_USERS_MANAGE)
     async def update_user(self, user_id: UUID, command: UpdateUserCommand) -> UserView:
-        return await self._repository.update_user(user_id, command)
+        return await self._store.update_user(user_id, command)
 
     @authorize(IDENTITY_USERS_MANAGE)
     async def set_user_active(self, user_id: UUID, command: SetUserActiveCommand) -> UserView:
-        return await self._repository.set_user_active(user_id, command)
+        return await self._store.set_user_active(user_id, command)
 
     @authorize(IDENTITY_USERS_MANAGE)
     async def delete_user(self, user_id: UUID, command: IdentityConcurrencyCommand) -> None:
-        await self._repository.delete_user(user_id, command.concurrency_version)
+        await self._store.delete_user(user_id, command.concurrency_version)
 
     @authorize(IDENTITY_USERS_MANAGE)
     async def set_password(self, user_id: UUID, command: SetPasswordCommand) -> None:
         password_hash = await self._passwords.hash(command.new_password.get_secret_value())
-        await self._repository.set_password(user_id, password_hash, command.concurrency_version)
+        await self._credentials.set_password(user_id, password_hash, command.concurrency_version)
 
     @authorize(IDENTITY_ROLES_MANAGE)
     async def create_role(self, command: CreateRoleCommand) -> RoleView:
         normalized = _normalize_name(command.name, role="role name")
-        if await self._repository.find_role_by_normalized_name(normalized) is not None:
+        if await self._store.find_role_by_normalized_name(normalized) is not None:
             raise IdentityConflictError(resource="role")
         role = IdentityRole(uuid4(), command.name.strip(), normalized, 0)
-        await self._repository.create_role(role)
+        await self._store.create_role(role)
         return RoleView(role.role_id, role.name, (), role.concurrency_version)
 
     @authorize(IDENTITY_ROLES_MANAGE)
     async def get_roles(self, query: PagedResultRequestDto) -> PagedResult[RoleView]:
-        return await self._repository.list_roles(query)
+        return await self._store.list_roles(query)
 
     @authorize(IDENTITY_ROLES_MANAGE)
     async def get_role(self, role_id: UUID) -> RoleView:
-        return await self._repository.get_role(role_id)
+        return await self._store.get_role(role_id)
 
     @authorize(IDENTITY_ROLES_MANAGE)
     async def update_role(self, role_id: UUID, command: UpdateRoleCommand) -> RoleView:
-        return await self._repository.update_role(role_id, command)
+        return await self._store.update_role(role_id, command)
 
     @authorize(IDENTITY_ROLES_MANAGE)
     async def delete_role(self, role_id: UUID, command: IdentityConcurrencyCommand) -> None:
-        await self._repository.delete_role(role_id, command.concurrency_version)
+        await self._store.delete_role(role_id, command.concurrency_version)
 
     @authorize(IDENTITY_USERS_MANAGE, IDENTITY_ROLES_MANAGE)
     async def get_user_roles(self, user_id: UUID) -> UserRolesView:
-        user = await self._repository.get_user_view(user_id)
+        user = await self._store.get_user_view(user_id)
         return UserRolesView(role_ids=user.role_ids, concurrency_version=user.concurrency_version)
 
     @authorize(IDENTITY_ROLES_MANAGE)
     async def get_role_permissions(self, role_id: UUID) -> RolePermissionsView:
-        role = await self._repository.get_role(role_id)
+        role = await self._store.get_role(role_id)
         return RolePermissionsView(
             permissions=role.permissions, concurrency_version=role.concurrency_version
         )
@@ -147,7 +150,7 @@ class DefaultIdentityManagementApplicationService(ApplicationService):
     @authorize(IDENTITY_USERS_MANAGE, IDENTITY_ROLES_MANAGE)
     async def set_user_roles(self, user_id: UUID, command: SetUserRolesCommand) -> UserRolesView:
         role_ids = tuple(dict.fromkeys(command.role_ids))
-        return await self._repository.set_user_roles(user_id, role_ids, command.concurrency_version)
+        return await self._store.set_user_roles(user_id, role_ids, command.concurrency_version)
 
     @authorize(IDENTITY_ROLES_MANAGE)
     async def set_role_permissions(
@@ -159,7 +162,7 @@ class DefaultIdentityManagementApplicationService(ApplicationService):
         unknown = tuple(item for item in names if item not in self._permissions)
         if unknown:
             raise IdentityResourceNotFoundError(resource="permission")
-        return await self._repository.set_role_permissions(
+        return await self._store.set_role_permissions(
             role_id,
             tuple(item.value for item in names),
             command.concurrency_version,

python_ddd_framework/identity/models.py

@@ -0,0 +1,86 @@
+"""Identity 用户、角色与 refresh 会话的不可变领域值。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from datetime import datetime
+from enum import Enum
+from uuid import UUID
+
+from ..extensions.contracts import ExtensionProperties
+from .domain_rules import _check_version, _normalize_name
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityUser:
+    user_id: UUID
+    username: str
+    normalized_username: str
+    password_hash: str
+    is_active: bool
+    failed_access_count: int
+    lockout_end: datetime | None
+    permission_version: int
+    extra_properties: ExtensionProperties = field(default_factory=ExtensionProperties)
+    concurrency_version: int = 0
+
+    def renamed(self, username: str, expected_version: int) -> IdentityUser:
+        _check_version(self.concurrency_version, expected_version)
+        return replace(
+            self,
+            username=username.strip(),
+            normalized_username=_normalize_name(username, role="username"),
+            concurrency_version=self.concurrency_version + 1,
+        )
+
+    def with_active(self, is_active: bool, expected_version: int) -> IdentityUser:
+        _check_version(self.concurrency_version, expected_version)
+        return replace(
+            self,
+            is_active=is_active,
+            concurrency_version=self.concurrency_version + (self.is_active != is_active),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityRole:
+    role_id: UUID
+    name: str
+    normalized_name: str
+    permission_version: int
+    concurrency_version: int = 0
+
+    def renamed(self, name: str, expected_version: int) -> IdentityRole:
+        _check_version(self.concurrency_version, expected_version)
+        return replace(
+            self,
+            name=name.strip(),
+            normalized_name=_normalize_name(name, role="role name"),
+            concurrency_version=self.concurrency_version + 1,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RefreshSession:
+    session_id: UUID
+    user_id: UUID
+    family_id: UUID
+    token_hash: str
+    created_at: datetime
+    family_created_at: datetime
+    last_used_at: datetime
+    revoked_at: datetime | None = None
+    replaced_by_session_id: UUID | None = None
+
+
+class RefreshRotationStatus(Enum):
+    ROTATED = "rotated"
+    NOT_FOUND = "not_found"
+    REUSED = "reused"
+    EXPIRED = "expired"
+
+
+@dataclass(frozen=True, slots=True)
+class RefreshRotationResult:
+    status: RefreshRotationStatus
+    session: RefreshSession | None

python_ddd_framework/identity/module.py

@@ -10,10 +10,8 @@ from ..extensions.contracts import ExtensionPoints
 from ..lifecycle import ConfigureContext
 from ..modularity import AppModule, ModuleRef
 from ..seeding.module import DataSeedingModule
-from .contracts import (
-    IDENTITY_USER_EXTENSION,
-    IdentityOptions,
-)
+from .extensions import IDENTITY_USER_EXTENSION
+from .options import IdentityOptions
 from .passwords import PasswordHasher
 from .services import (
     IdentityAuthenticator,
@@ -32,6 +30,7 @@ class IdentityModule(AppModule):
     scan_packages = (
         "python_ddd_framework.identity.application",
         "python_ddd_framework.identity.management",
+        "python_ddd_framework.identity.seeding",
         "python_ddd_framework.identity.permissions",
     )
 

python_ddd_framework/identity/options.py

@@ -0,0 +1,54 @@
+"""Identity 的 Host 配置与 keyring 校验。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import timedelta
+
+from pydantic import Field, SecretStr, field_validator, model_validator
+
+from ..options import BaseOptions
+from .domain_rules import _normalize_name
+
+
+class IdentityOptions(BaseOptions):
+    issuer: str
+    audience: str
+    active_kid: str
+    keys: Mapping[str, SecretStr]
+    access_token_lifetime: timedelta = Field(default=timedelta(minutes=15), ge=timedelta(seconds=1))
+    refresh_inactivity_lifetime: timedelta = Field(default=timedelta(days=30), gt=timedelta(0))
+    refresh_absolute_lifetime: timedelta = Field(default=timedelta(days=90), gt=timedelta(0))
+    failed_attempt_limit: int = Field(default=5, ge=1)
+    lockout_duration: timedelta = Field(default=timedelta(minutes=15), ge=timedelta(seconds=1))
+    seed_admin_username: str | None = None
+    seed_admin_password: SecretStr | None = None
+
+    @field_validator("issuer", "audience", "active_kid")
+    @classmethod
+    def _validate_identifier(cls, value: str) -> str:
+        if not value or value != value.strip():
+            raise ValueError("JWT identifier must be a non-empty trimmed string")
+        return value
+
+    @field_validator("keys")
+    @classmethod
+    def _validate_keys(cls, value: Mapping[str, SecretStr]) -> Mapping[str, SecretStr]:
+        if not value:
+            raise ValueError("JWT keyring must contain at least one key")
+        for kid, secret in value.items():
+            if not kid or kid != kid.strip():
+                raise ValueError("JWT kid must be a non-empty trimmed string")
+            if len(secret.get_secret_value().encode("utf-8")) < 32:
+                raise ValueError("HS256 keys must contain at least 256 bits")
+        return value
+
+    @model_validator(mode="after")
+    def _validate_active_and_seed(self) -> IdentityOptions:
+        if self.active_kid not in self.keys:
+            raise ValueError("active_kid must reference the JWT keyring")
+        if (self.seed_admin_username is None) != (self.seed_admin_password is None):
+            raise ValueError("seed administrator username and password must be configured together")
+        if self.seed_admin_username is not None:
+            _normalize_name(self.seed_admin_username, role="seed administrator username")
+        return self

python_ddd_framework/identity/seeding.py

@@ -0,0 +1,59 @@
+"""管理员初始化贡献；发现和每项独立 UoW 由 DataSeedingModule 管理。"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from ..authorization import PermissionCatalog
+from ..options import Options
+from ..seeding.contracts import DataSeedContributor
+from .domain_rules import _normalize_name
+from .models import IdentityRole, IdentityUser
+from .options import IdentityOptions
+from .passwords import PasswordHasher
+from .stores import IdentityManagementStore
+
+
+class IdentityAdminSeedContributor(DataSeedContributor):
+    def __init__(
+        self,
+        store: IdentityManagementStore,
+        passwords: PasswordHasher,
+        permissions: PermissionCatalog,
+        options: Options[IdentityOptions],
+    ) -> None:
+        self._store = store
+        self._passwords = passwords
+        self._permissions = permissions
+        self._options = options.value
+
+    async def seed(self) -> None:
+        username = self._options.seed_admin_username
+        password = self._options.seed_admin_password
+        if username is None or password is None:
+            return
+        normalized_username = _normalize_name(username, role="seed administrator username")
+        user = await self._store.find_user_by_normalized_username(normalized_username)
+        if user is None:
+            user = IdentityUser(
+                uuid4(),
+                username.strip(),
+                normalized_username,
+                await self._passwords.hash(password.get_secret_value()),
+                True,
+                0,
+                None,
+                0,
+            )
+            await self._store.create_user(user)
+        normalized_role = "administrator"
+        role = await self._store.find_role_by_normalized_name(normalized_role)
+        if role is None:
+            role = IdentityRole(uuid4(), "Administrator", normalized_role, 0)
+            await self._store.create_role(role)
+        await self._store.set_role_permissions(
+            role.role_id,
+            tuple(item.name.value for item in self._permissions.definitions),
+            role.concurrency_version,
+        )
+        await self._store.set_user_roles(user.user_id, (role.role_id,), user.concurrency_version)

python_ddd_framework/identity/services.py

@@ -23,8 +23,8 @@ from ..caching import (
     cache_name,
 )
 from ..options import Options
-from .contracts import IdentityAccessStore
 from .errors import InvalidCredentialsError
+from .stores import IdentityAccessStore
 from .tokens import JwtTokenService
 
 _LOGGER = logging.getLogger(__name__)

python_ddd_framework/identity/sqlalchemy/module.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dishka import Provider, Scope
+from dishka import AnyOf, Provider, Scope
 
 from ...lifecycle import ConfigureContext
 from ...modularity import AppModule
@@ -12,14 +12,15 @@ from ...sqlalchemy import (
     SqlAlchemyPersistenceModule,
     contributes_sqlalchemy_models,
 )
-from ..contracts import (
-    IDENTITY_USER_EXTENSION,
+from ..extensions import IDENTITY_USER_EXTENSION
+from ..module import IdentityModule
+from ..stores import (
     IdentityAccessStore,
+    IdentityCredentialStore,
     IdentityLoginStore,
-    IdentityRepository,
+    IdentityManagementStore,
     RefreshSessionStore,
 )
-from ..module import IdentityModule
 from .models import IdentityBase, UserRow, UserRowValues
 from .repository import SqlAlchemyIdentityRepository
 from .stores import (
@@ -50,7 +51,9 @@ class SqlAlchemyIdentityModule(AppModule):
         provider = Provider()
         provider.provide(
             SqlAlchemyIdentityRepository,
-            provides=IdentityRepository,
+            provides=AnyOf[
+                SqlAlchemyIdentityRepository, IdentityCredentialStore, IdentityManagementStore
+            ],
             scope=Scope.REQUEST,
         )
         provider.provide(

python_ddd_framework/identity/sqlalchemy/repository.py

@@ -12,10 +12,8 @@ from ...application_services import PagedResult, PagedResultRequestDto
 from ...domain import OptimisticConcurrencyError
 from ...extensions import ExtensionProperties
 from ...sqlalchemy import SqlAlchemyModelCatalog, SqlAlchemySessionProvider
-from ..contracts import (
-    IDENTITY_USER_EXTENSION,
-    IdentityRole,
-    IdentityUser,
+from ..domain_rules import _check_version
+from ..dtos import (
     RolePermissionsView,
     RoleView,
     SetUserActiveCommand,
@@ -23,9 +21,10 @@ from ..contracts import (
     UpdateUserCommand,
     UserRolesView,
     UserView,
-    _check_version,
 )
 from ..errors import IdentityConflictError, IdentityResourceNotFoundError
+from ..extensions import IDENTITY_USER_EXTENSION
+from ..models import IdentityRole, IdentityUser
 from .models import (
     RolePermissionRow,
     RoleRow,

python_ddd_framework/identity/sqlalchemy/session_security.py

@@ -9,9 +9,7 @@ from uuid import UUID
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from ..contracts import (
-    IdentityOptions,
-)
+from ..options import IdentityOptions
 from .models import (
     RefreshSessionRow,
 )

python_ddd_framework/identity/sqlalchemy/stores.py

@@ -11,14 +11,9 @@ from ...authorization import CurrentUser, RolePermissionVersion
 from ...options import Options
 from ...sqlalchemy import FrameworkAsyncSession, SqlAlchemyModelCatalog
 from ...sqlalchemy.runtime import _SqlAlchemyEngineRegistry
-from ..contracts import (
-    IDENTITY_USER_EXTENSION,
-    IdentityOptions,
-    IdentityUser,
-    RefreshRotationResult,
-    RefreshRotationStatus,
-    RefreshSession,
-)
+from ..extensions import IDENTITY_USER_EXTENSION
+from ..models import IdentityUser, RefreshRotationResult, RefreshRotationStatus, RefreshSession
+from ..options import IdentityOptions
 from .models import (
     RefreshSessionRow,
     RolePermissionRow,
@@ -80,13 +75,14 @@ class SqlAlchemyIdentityAccessStore:
                     .order_by(RoleRow.role_id)
                 )
             ).all()
+            # 驱动 UUID 子类止于持久化边界；调用方可将身份值放入稳定领域事件。
             return CurrentUser(
-                user_id=user.user_id,
-                session_id=refresh.session_id,
+                user_id=UUID(bytes=user.user_id.bytes),
+                session_id=UUID(bytes=refresh.session_id.bytes),
                 username=user.username,
                 permission_version=user.permission_version,
                 role_versions=tuple(
-                    RolePermissionVersion(role_id=role_id, version=version)
+                    RolePermissionVersion(role_id=UUID(bytes=role_id.bytes), version=version)
                     for role_id, version in role_rows
                 ),
             )
@@ -222,26 +218,9 @@ class SqlAlchemyRefreshSessionStore:
         now: datetime,
     ) -> RefreshRotationResult:
         async with self._session() as session, session.begin():
-            identity = (
-                await session.execute(
-                    select(RefreshSessionRow.user_id, RefreshSessionRow.family_id).where(
-                        RefreshSessionRow.token_hash == token_hash
-                    )
-                )
-            ).one_or_none()
-            if identity is None:
-                return RefreshRotationResult(RefreshRotationStatus.NOT_FOUND, None)
-            user_id, family_id = identity
-            await _lock_identity_user(session, user_id)
-            await _lock_refresh_family(session, family_id)
-            current = await session.scalar(
-                select(RefreshSessionRow)
-                .where(RefreshSessionRow.token_hash == token_hash)
-                .with_for_update()
-            )
+            current = await self._locked_session(session, token_hash)
             if current is None:
                 return RefreshRotationResult(RefreshRotationStatus.NOT_FOUND, None)
-            assert current.family_id == family_id
             if current.revoked_at is not None or current.replaced_by_session_id is not None:
                 await _revoke_family(session, current.family_id, now=now)
                 return RefreshRotationResult(RefreshRotationStatus.REUSED, None)
@@ -266,27 +245,36 @@ class SqlAlchemyRefreshSessionStore:
 
     async def revoke(self, token_hash: str, *, now: datetime) -> None:
         async with self._session() as session, session.begin():
-            identity = (
-                await session.execute(
-                    select(RefreshSessionRow.user_id, RefreshSessionRow.family_id).where(
-                        RefreshSessionRow.token_hash == token_hash
-                    )
-                )
-            ).one_or_none()
-            if identity is None:
-                return
-            user_id, family_id = identity
-            await _lock_identity_user(session, user_id)
-            await _lock_refresh_family(session, family_id)
-            current = await session.scalar(
-                select(RefreshSessionRow)
-                .where(RefreshSessionRow.token_hash == token_hash)
-                .with_for_update()
-            )
+            current = await self._locked_session(session, token_hash)
             if current is not None:
-                assert current.family_id == family_id
                 await _revoke_family(session, current.family_id, now=now)
 
+    async def _locked_session(
+        self, session: FrameworkAsyncSession, token_hash: str
+    ) -> RefreshSessionRow | None:
+        identity = (
+            await session.execute(
+                select(RefreshSessionRow.user_id, RefreshSessionRow.family_id).where(
+                    RefreshSessionRow.token_hash == token_hash
+                )
+            )
+        ).one_or_none()
+        if identity is None:
+            return None
+        user_id, family_id = identity
+        # 身份预读不授予变更权；user gate → family advisory → row 后重读，
+        # 保持凭据撤销与 refresh 的共同锁顺序，业务分支由 rotate/revoke 决定。
+        await _lock_identity_user(session, user_id)
+        await _lock_refresh_family(session, family_id)
+        current = await session.scalar(
+            select(RefreshSessionRow)
+            .where(RefreshSessionRow.token_hash == token_hash)
+            .with_for_update()
+        )
+        if current is not None:
+            assert current.family_id == family_id
+        return current
+
     def _session(self) -> FrameworkAsyncSession:
         return FrameworkAsyncSession(self._engines.get("default"), expire_on_commit=False)