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

python_ddd_framework/identity/contracts.py

@@ -1,448 +1,75 @@
-"""Identity 的 HTTP/Application contracts、持久化值与 Host keyring Options。"""
+"""Identity 应用服务契约与所属权限名称。"""
 
 from __future__ import annotations
 
-from collections.abc import Mapping
-from dataclasses import dataclass, field, replace
-from datetime import datetime, timedelta
-from enum import Enum
-from typing import Annotated, Protocol
+from typing import Protocol
 from uuid import UUID
 
-from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator, model_validator
-
 from ..application_services import ApplicationServiceContract, PagedResult, PagedResultRequestDto
-from ..authorization import (
-    CurrentUser,
-    PermissionName,
-    RolePermissionVersion,
-)
-from ..domain import OptimisticConcurrencyError
-from ..extensions.contracts import ExtensibleModel, ExtensionProperties, ExtensionTarget
-from ..options import BaseOptions
+from ..authorization import PermissionName
+from . import dtos
 
 IDENTITY_USERS_MANAGE = PermissionName("identity.users.manage")
-IDENTITY_ROLES_MANAGE = PermissionName("identity.roles.manage")
-
-
-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
-
-
-class LoginCommand(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    username: Annotated[str, Field(min_length=1, max_length=120)]
-    password: SecretStr
-
-
-class RefreshTokenCommand(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    refresh_token: SecretStr
-
-
-class RevokeTokenCommand(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    refresh_token: SecretStr
-
-
-class CreateUserCommand(ExtensibleModel):
-    model_config = ConfigDict(frozen=True)
-
-    username: Annotated[str, Field(min_length=1, max_length=120)]
-    password: Annotated[SecretStr, Field(min_length=12, max_length=1024)]
-
-    @field_validator("username")
-    @classmethod
-    def _validate_username(cls, value: str) -> str:
-        _normalize_name(value, role="username")
-        return value.strip()
-
-
-class CreateRoleCommand(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    name: Annotated[str, Field(min_length=1, max_length=120)]
-
-    @field_validator("name")
-    @classmethod
-    def _validate_name(cls, value: str) -> str:
-        _normalize_name(value, role="role name")
-        return value.strip()
-
-
-class IdentityConcurrencyCommand(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    concurrency_version: Annotated[int, Field(ge=0)]
-
-
-class UpdateUserCommand(ExtensibleModel):
-    model_config = ConfigDict(frozen=True)
-
-    username: Annotated[str, Field(min_length=1, max_length=120)]
-    concurrency_version: Annotated[int, Field(ge=0)]
-
-    @field_validator("username")
-    @classmethod
-    def _validate_username(cls, value: str) -> str:
-        _normalize_name(value, role="username")
-        return value.strip()
-
-
-class SetUserActiveCommand(IdentityConcurrencyCommand):
-    is_active: bool
-
-
-class UpdateRoleCommand(IdentityConcurrencyCommand):
-    name: Annotated[str, Field(min_length=1, max_length=120)]
-
-    @field_validator("name")
-    @classmethod
-    def _validate_name(cls, value: str) -> str:
-        _normalize_name(value, role="role name")
-        return value.strip()
-
-
-class ChangePasswordCommand(IdentityConcurrencyCommand):
-    old_password: SecretStr
-    new_password: Annotated[SecretStr, Field(min_length=12, max_length=1024)]
-
-
-class SetPasswordCommand(IdentityConcurrencyCommand):
-    new_password: Annotated[SecretStr, Field(min_length=12, max_length=1024)]
-
-
-class SetUserRolesCommand(IdentityConcurrencyCommand):
-    model_config = ConfigDict(frozen=True)
-
-    role_ids: tuple[UUID, ...]
-
-
-class SetRolePermissionsCommand(IdentityConcurrencyCommand):
-    model_config = ConfigDict(frozen=True)
-
-    permissions: tuple[str, ...]
-
-
-@dataclass(frozen=True, slots=True)
-class TokenPair:
-    access_token: str
-    refresh_token: str
-    token_type: str
-    expires_in: int
-
-
-class UserView(ExtensibleModel):
-    user_id: UUID
-    username: str
-    is_active: bool
-    role_ids: tuple[UUID, ...]
-    concurrency_version: int
-
-
-@dataclass(frozen=True, slots=True)
-class RoleView:
-    role_id: UUID
-    name: str
-    permissions: tuple[str, ...]
-    concurrency_version: int
-
-
-class UserRolesView(BaseModel):
-    role_ids: tuple[UUID, ...]
-    concurrency_version: int
-
 
-class RolePermissionsView(BaseModel):
-    permissions: tuple[str, ...]
-    concurrency_version: int
 
-
-@dataclass(frozen=True, slots=True)
-class CurrentUserView:
-    user_id: UUID
-    session_id: UUID
-    username: str
-    concurrency_version: int
-
-
-@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),
-        )
-
-
-IDENTITY_USER_EXTENSION = ExtensionTarget(
-    "identity.user", (CreateUserCommand, UpdateUserCommand, UserView), IdentityUser
-)
-
-
-@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
-
-
-class IdentityRepository(Protocol):
-    async def find_user_by_normalized_username(
-        self, normalized_username: str
-    ) -> IdentityUser | None: ...
-
-    async def create_user(self, user: IdentityUser) -> None: ...
-
-    async def get_user(self, user_id: UUID) -> IdentityUser: ...
-
-    async def get_user_view(self, user_id: UUID) -> UserView: ...
-
-    async def list_users(self, query: PagedResultRequestDto) -> PagedResult[UserView]: ...
-
-    async def update_user(self, user_id: UUID, command: UpdateUserCommand) -> UserView: ...
-
-    async def set_user_active(self, user_id: UUID, command: SetUserActiveCommand) -> UserView: ...
-
-    async def delete_user(self, user_id: UUID, concurrency_version: int) -> None: ...
-
-    async def set_password(
-        self,
-        user_id: UUID,
-        password_hash: str,
-        concurrency_version: int,
-        *,
-        expected_password_hash: str | None = None,
-    ) -> None: ...
-
-    async def create_role(self, role: IdentityRole) -> None: ...
-
-    async def find_role_by_normalized_name(self, normalized_name: str) -> IdentityRole | None: ...
-
-    async def get_role(self, role_id: UUID) -> RoleView: ...
-
-    async def list_roles(self, query: PagedResultRequestDto) -> PagedResult[RoleView]: ...
-
-    async def update_role(self, role_id: UUID, command: UpdateRoleCommand) -> RoleView: ...
-
-    async def delete_role(self, role_id: UUID, concurrency_version: int) -> None: ...
-
-    async def set_user_roles(
-        self, user_id: UUID, role_ids: tuple[UUID, ...], concurrency_version: int
-    ) -> UserRolesView: ...
-
-    async def set_role_permissions(
-        self, role_id: UUID, permissions: tuple[str, ...], concurrency_version: int
-    ) -> RolePermissionsView: ...
-
-
-class IdentityAccessStore(Protocol):
-    async def load_current_user(
-        self,
-        user_id: UUID,
-        session_id: UUID,
-        now: datetime,
-    ) -> CurrentUser | None: ...
-
-    async def permissions_for_roles(
-        self, role_versions: tuple[RolePermissionVersion, ...]
-    ) -> frozenset[str]: ...
-
-
-class IdentityLoginStore(Protocol):
-    async def find_user(self, normalized_username: str) -> IdentityUser | None: ...
-
-    async def record_failure(
-        self,
-        user_id: UUID,
-        *,
-        now: datetime,
-        attempt_limit: int,
-        lockout_duration_seconds: int,
-    ) -> None: ...
-
-    async def complete_success(
-        self,
-        user_id: UUID,
-        *,
-        expected_password_hash: str,
-        updated_password_hash: str | None,
-        session: RefreshSession,
-        now: datetime,
-    ) -> bool: ...
-
-
-class RefreshSessionStore(Protocol):
-    async def rotate(
-        self,
-        token_hash: str,
-        *,
-        replacement_id: UUID,
-        replacement_hash: str,
-        now: datetime,
-    ) -> RefreshRotationResult: ...
-
-    async def revoke(self, token_hash: str, *, now: datetime) -> None: ...
+IDENTITY_ROLES_MANAGE = PermissionName("identity.roles.manage")
 
 
 class AuthenticationApplicationService(ApplicationServiceContract, Protocol):
-    async def login(self, command: LoginCommand) -> TokenPair: ...
+    async def login(self, command: dtos.LoginCommand) -> dtos.TokenPair: ...
 
-    async def refresh(self, command: RefreshTokenCommand) -> TokenPair: ...
+    async def refresh(self, command: dtos.RefreshTokenCommand) -> dtos.TokenPair: ...
 
-    async def revoke(self, command: RevokeTokenCommand) -> None: ...
+    async def revoke(self, command: dtos.RevokeTokenCommand) -> None: ...
 
-    async def me(self) -> CurrentUserView: ...
+    async def me(self) -> dtos.CurrentUserView: ...
 
-    async def change_password(self, command: ChangePasswordCommand) -> None: ...
+    async def change_password(self, command: dtos.ChangePasswordCommand) -> None: ...
 
 
 class IdentityManagementApplicationService(ApplicationServiceContract, Protocol):
-    async def create_user(self, command: CreateUserCommand) -> UserView: ...
+    async def create_user(self, command: dtos.CreateUserCommand) -> dtos.UserView: ...
 
-    async def get_user(self, user_id: UUID) -> UserView: ...
+    async def get_user(self, user_id: UUID) -> dtos.UserView: ...
 
-    async def get_users(self, query: PagedResultRequestDto) -> PagedResult[UserView]: ...
+    async def get_users(self, query: PagedResultRequestDto) -> PagedResult[dtos.UserView]: ...
 
-    async def update_user(self, user_id: UUID, command: UpdateUserCommand) -> UserView: ...
+    async def update_user(
+        self, user_id: UUID, command: dtos.UpdateUserCommand
+    ) -> dtos.UserView: ...
 
-    async def set_user_active(self, user_id: UUID, command: SetUserActiveCommand) -> UserView: ...
+    async def set_user_active(
+        self, user_id: UUID, command: dtos.SetUserActiveCommand
+    ) -> dtos.UserView: ...
 
-    async def delete_user(self, user_id: UUID, command: IdentityConcurrencyCommand) -> None: ...
+    async def delete_user(
+        self, user_id: UUID, command: dtos.IdentityConcurrencyCommand
+    ) -> None: ...
 
-    async def set_password(self, user_id: UUID, command: SetPasswordCommand) -> None: ...
+    async def set_password(self, user_id: UUID, command: dtos.SetPasswordCommand) -> None: ...
 
-    async def create_role(self, command: CreateRoleCommand) -> RoleView: ...
+    async def create_role(self, command: dtos.CreateRoleCommand) -> dtos.RoleView: ...
 
-    async def get_role(self, role_id: UUID) -> RoleView: ...
+    async def get_role(self, role_id: UUID) -> dtos.RoleView: ...
 
-    async def get_roles(self, query: PagedResultRequestDto) -> PagedResult[RoleView]: ...
+    async def get_roles(self, query: PagedResultRequestDto) -> PagedResult[dtos.RoleView]: ...
 
-    async def update_role(self, role_id: UUID, command: UpdateRoleCommand) -> RoleView: ...
+    async def update_role(
+        self, role_id: UUID, command: dtos.UpdateRoleCommand
+    ) -> dtos.RoleView: ...
 
-    async def delete_role(self, role_id: UUID, command: IdentityConcurrencyCommand) -> None: ...
+    async def delete_role(
+        self, role_id: UUID, command: dtos.IdentityConcurrencyCommand
+    ) -> None: ...
 
-    async def get_user_roles(self, user_id: UUID) -> UserRolesView: ...
+    async def get_user_roles(self, user_id: UUID) -> dtos.UserRolesView: ...
 
-    async def get_role_permissions(self, role_id: UUID) -> RolePermissionsView: ...
+    async def get_role_permissions(self, role_id: UUID) -> dtos.RolePermissionsView: ...
 
     async def set_user_roles(
-        self, user_id: UUID, command: SetUserRolesCommand
-    ) -> UserRolesView: ...
+        self, user_id: UUID, command: dtos.SetUserRolesCommand
+    ) -> dtos.UserRolesView: ...
 
     async def set_role_permissions(
-        self, role_id: UUID, command: SetRolePermissionsCommand
-    ) -> RolePermissionsView: ...
-
-
-def _normalize_name(value: str, *, role: str) -> str:
-    normalized = value.strip().casefold()
-    if not normalized or len(normalized) > 120:
-        raise ValueError(f"{role} must contain between 1 and 120 characters")
-    return normalized
-
-
-def _check_version(actual: int, expected: int) -> None:
-    if actual != expected:
-        raise OptimisticConcurrencyError
+        self, role_id: UUID, command: dtos.SetRolePermissionsCommand
+    ) -> dtos.RolePermissionsView: ...

python_ddd_framework/identity/domain_rules.py

@@ -0,0 +1,17 @@
+"""Identity 名称规范化与领域并发版本规则。"""
+
+from __future__ import annotations
+
+from ..domain import OptimisticConcurrencyError
+
+
+def _normalize_name(value: str, *, role: str) -> str:
+    normalized = value.strip().casefold()
+    if not normalized or len(normalized) > 120:
+        raise ValueError(f"{role} must contain between 1 and 120 characters")
+    return normalized
+
+
+def _check_version(actual: int, expected: int) -> None:
+    if actual != expected:
+        raise OptimisticConcurrencyError

python_ddd_framework/identity/dtos.py

@@ -0,0 +1,152 @@
+"""Identity 应用服务的输入、输出与并发版本。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+from ..extensions.contracts import ExtensibleModel
+from .domain_rules import _normalize_name
+
+
+class LoginCommand(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    username: Annotated[str, Field(min_length=1, max_length=120)]
+    password: SecretStr
+
+
+class RefreshTokenCommand(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    refresh_token: SecretStr
+
+
+class RevokeTokenCommand(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    refresh_token: SecretStr
+
+
+class CreateUserCommand(ExtensibleModel):
+    model_config = ConfigDict(frozen=True)
+
+    username: Annotated[str, Field(min_length=1, max_length=120)]
+    password: Annotated[SecretStr, Field(min_length=12, max_length=1024)]
+
+    @field_validator("username")
+    @classmethod
+    def _validate_username(cls, value: str) -> str:
+        _normalize_name(value, role="username")
+        return value.strip()
+
+
+class CreateRoleCommand(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: Annotated[str, Field(min_length=1, max_length=120)]
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, value: str) -> str:
+        _normalize_name(value, role="role name")
+        return value.strip()
+
+
+class IdentityConcurrencyCommand(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    concurrency_version: Annotated[int, Field(ge=0)]
+
+
+class UpdateUserCommand(ExtensibleModel):
+    model_config = ConfigDict(frozen=True)
+
+    username: Annotated[str, Field(min_length=1, max_length=120)]
+    concurrency_version: Annotated[int, Field(ge=0)]
+
+    @field_validator("username")
+    @classmethod
+    def _validate_username(cls, value: str) -> str:
+        _normalize_name(value, role="username")
+        return value.strip()
+
+
+class SetUserActiveCommand(IdentityConcurrencyCommand):
+    is_active: bool
+
+
+class UpdateRoleCommand(IdentityConcurrencyCommand):
+    name: Annotated[str, Field(min_length=1, max_length=120)]
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, value: str) -> str:
+        _normalize_name(value, role="role name")
+        return value.strip()
+
+
+class ChangePasswordCommand(IdentityConcurrencyCommand):
+    old_password: SecretStr
+    new_password: Annotated[SecretStr, Field(min_length=12, max_length=1024)]
+
+
+class SetPasswordCommand(IdentityConcurrencyCommand):
+    new_password: Annotated[SecretStr, Field(min_length=12, max_length=1024)]
+
+
+class SetUserRolesCommand(IdentityConcurrencyCommand):
+    model_config = ConfigDict(frozen=True)
+
+    role_ids: tuple[UUID, ...]
+
+
+class SetRolePermissionsCommand(IdentityConcurrencyCommand):
+    model_config = ConfigDict(frozen=True)
+
+    permissions: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TokenPair:
+    access_token: str
+    refresh_token: str
+    token_type: str
+    expires_in: int
+
+
+class UserView(ExtensibleModel):
+    user_id: UUID
+    username: str
+    is_active: bool
+    role_ids: tuple[UUID, ...]
+    concurrency_version: int
+
+
+@dataclass(frozen=True, slots=True)
+class RoleView:
+    role_id: UUID
+    name: str
+    permissions: tuple[str, ...]
+    concurrency_version: int
+
+
+class UserRolesView(BaseModel):
+    role_ids: tuple[UUID, ...]
+    concurrency_version: int
+
+
+class RolePermissionsView(BaseModel):
+    permissions: tuple[str, ...]
+    concurrency_version: int
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentUserView:
+    user_id: UUID
+    session_id: UUID
+    username: str
+    concurrency_version: int

python_ddd_framework/identity/extensions.py

@@ -0,0 +1,9 @@
+"""Identity 用户扩展点连接 DTO 与领域值，由所属 Module 声明。"""
+
+from ..extensions.contracts import ExtensionTarget
+from .dtos import CreateUserCommand, UpdateUserCommand, UserView
+from .models import IdentityUser
+
+IDENTITY_USER_EXTENSION = ExtensionTarget(
+    "identity.user", (CreateUserCommand, UpdateUserCommand, UserView), IdentityUser
+)