python-platform 0.1.1__py3-none-any.whl

python_platform/identity/application.py

@@ -0,0 +1,287 @@
+"""Identity Application Services：认证、refresh family 与管理员业务编排。"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from uuid import UUID, uuid4
+
+from ..application_services import ApplicationService, DataSeedContributor, application_service
+from ..authorization import (
+    CurrentUser,
+    PermissionCatalog,
+    PermissionName,
+    allow_anonymous,
+    authorize,
+)
+from ..options import Options
+from .contracts import (
+    IDENTITY_ROLES_MANAGE,
+    IDENTITY_USERS_MANAGE,
+    AuthenticationApplicationService,
+    CreateRoleCommand,
+    CreateUserCommand,
+    CurrentUserView,
+    IdentityLoginStore,
+    IdentityManagementApplicationService,
+    IdentityOptions,
+    IdentityRepository,
+    IdentityRole,
+    IdentityUser,
+    LoginCommand,
+    RefreshRotationStatus,
+    RefreshSession,
+    RefreshSessionStore,
+    RefreshTokenCommand,
+    RevokeTokenCommand,
+    RoleView,
+    SetRolePermissionsCommand,
+    SetUserRolesCommand,
+    TokenPair,
+    UserView,
+    _normalize_name,
+)
+from .errors import (
+    IdentityConflictError,
+    IdentityResourceNotFoundError,
+    InvalidCredentialsError,
+)
+from .passwords import PasswordHasher
+from .tokens import (
+    ACCESS_TOKEN_LIFETIME,
+    BEARER_TOKEN_TYPE,
+    JwtTokenService,
+    hash_refresh_token,
+    new_refresh_token,
+)
+
+FAILED_ATTEMPT_LIMIT = 5
+LOCKOUT_DURATION = timedelta(minutes=15)
+
+
+@authorize()
+@application_service(provides=AuthenticationApplicationService)
+class _AuthenticationApplicationService(ApplicationService):
+    def __init__(
+        self,
+        login_store: IdentityLoginStore,
+        sessions: RefreshSessionStore,
+        passwords: PasswordHasher,
+        tokens: JwtTokenService,
+        current_user: CurrentUser,
+    ) -> None:
+        self._login_store = login_store
+        self._sessions = sessions
+        self._passwords = passwords
+        self._tokens = tokens
+        self._current_user = current_user
+
+    @allow_anonymous
+    async def login(self, command: LoginCommand) -> TokenPair:
+        now = datetime.now(UTC)
+        user = await self._login_store.find_user(_normalize_name(command.username, role="username"))
+        supplied_password = command.password.get_secret_value()
+        verified, updated_hash = await self._passwords.verify(
+            supplied_password,
+            user.password_hash if user is not None else None,
+        )
+        if user is None:
+            raise InvalidCredentialsError
+        if (
+            not user.is_active
+            or (user.lockout_end is not None and user.lockout_end > now)
+            or not verified
+        ):
+            if user.is_active and (user.lockout_end is None or user.lockout_end <= now):
+                await self._login_store.record_failure(
+                    user.user_id,
+                    now=now,
+                    attempt_limit=FAILED_ATTEMPT_LIMIT,
+                    lockout_duration_seconds=int(LOCKOUT_DURATION.total_seconds()),
+                )
+            raise InvalidCredentialsError
+
+        refresh_token = new_refresh_token()
+        session = _new_session(user.user_id, refresh_token, now=now)
+        completed = await self._login_store.complete_success(
+            user.user_id,
+            expected_password_hash=user.password_hash,
+            updated_password_hash=updated_hash,
+            session=session,
+            now=now,
+        )
+        if not completed:
+            raise InvalidCredentialsError
+        return self._token_pair(session, refresh_token, now=now)
+
+    @allow_anonymous
+    async def refresh(self, command: RefreshTokenCommand) -> TokenPair:
+        now = datetime.now(UTC)
+        refresh_token = new_refresh_token()
+        result = await self._sessions.rotate(
+            hash_refresh_token(command.refresh_token.get_secret_value()),
+            replacement_id=uuid4(),
+            replacement_hash=hash_refresh_token(refresh_token),
+            now=now,
+        )
+        if result.status is not RefreshRotationStatus.ROTATED or result.session is None:
+            raise InvalidCredentialsError
+        return self._token_pair(result.session, refresh_token, now=now)
+
+    @allow_anonymous
+    async def revoke(self, command: RevokeTokenCommand) -> None:
+        await self._sessions.revoke(
+            hash_refresh_token(command.refresh_token.get_secret_value()),
+            now=datetime.now(UTC),
+        )
+
+    async def me(self) -> CurrentUserView:
+        if (
+            self._current_user.user_id is None
+            or self._current_user.session_id is None
+            or self._current_user.username is None
+        ):
+            # Invocation authorization normally rejects first；此 guard 保持 implementation 完整。
+            raise InvalidCredentialsError
+        return CurrentUserView(
+            user_id=self._current_user.user_id,
+            session_id=self._current_user.session_id,
+            username=self._current_user.username,
+        )
+
+    def _token_pair(
+        self,
+        session: RefreshSession,
+        refresh_token: str,
+        *,
+        now: datetime,
+    ) -> TokenPair:
+        return TokenPair(
+            access_token=self._tokens.issue(session.user_id, session.session_id, now=now),
+            refresh_token=refresh_token,
+            token_type=BEARER_TOKEN_TYPE,
+            expires_in=int(ACCESS_TOKEN_LIFETIME.total_seconds()),
+        )
+
+
+@application_service(provides=IdentityManagementApplicationService)
+class _IdentityManagementApplicationService(ApplicationService):
+    def __init__(
+        self,
+        repository: IdentityRepository,
+        passwords: PasswordHasher,
+        permissions: PermissionCatalog,
+    ) -> None:
+        self._repository = repository
+        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:
+            raise IdentityConflictError(resource="user")
+        user = IdentityUser(
+            user_id=uuid4(),
+            username=command.username.strip(),
+            normalized_username=normalized,
+            password_hash=await self._passwords.hash(command.password.get_secret_value()),
+            is_active=True,
+            failed_access_count=0,
+            lockout_end=None,
+            permission_version=0,
+        )
+        await self._repository.create_user(user)
+        return UserView(user.user_id, user.username, user.is_active, ())
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def get_users(self) -> tuple[UserView, ...]:
+        return await self._repository.list_users()
+
+    @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:
+            raise IdentityConflictError(resource="role")
+        role = IdentityRole(uuid4(), command.name.strip(), normalized, 0)
+        await self._repository.create_role(role)
+        return RoleView(role.role_id, role.name, ())
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def get_roles(self) -> tuple[RoleView, ...]:
+        return await self._repository.list_roles()
+
+    @authorize(IDENTITY_USERS_MANAGE, IDENTITY_ROLES_MANAGE)
+    async def set_user_roles(self, user_id: UUID, command: SetUserRolesCommand) -> None:
+        role_ids = tuple(dict.fromkeys(command.role_ids))
+        await self._repository.set_user_roles(user_id, role_ids)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def set_role_permissions(self, role_id: UUID, command: SetRolePermissionsCommand) -> None:
+        names = tuple(PermissionName(item) for item in command.permissions)
+        if len(set(names)) != len(names):
+            raise IdentityConflictError(resource="role permission")
+        unknown = tuple(item for item in names if item not in self._permissions)
+        if unknown:
+            raise IdentityResourceNotFoundError(resource="permission")
+        await self._repository.set_role_permissions(
+            role_id,
+            tuple(item.value for item in names),
+        )
+
+
+@application_service()
+class IdentityAdminSeedContributor(DataSeedContributor):
+    def __init__(
+        self,
+        repository: IdentityRepository,
+        passwords: PasswordHasher,
+        permissions: PermissionCatalog,
+        options: Options[IdentityOptions],
+    ) -> None:
+        self._repository = repository
+        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._repository.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._repository.create_user(user)
+        normalized_role = "administrator"
+        role = await self._repository.find_role_by_normalized_name(normalized_role)
+        if role is None:
+            role = IdentityRole(uuid4(), "Administrator", normalized_role, 0)
+            await self._repository.create_role(role)
+        await self._repository.set_role_permissions(
+            role.role_id,
+            tuple(item.name.value for item in self._permissions.definitions),
+        )
+        await self._repository.set_user_roles(user.user_id, (role.role_id,))
+
+
+def _new_session(user_id: UUID, refresh_token: str, *, now: datetime) -> RefreshSession:
+    family_id = uuid4()
+    return RefreshSession(
+        session_id=uuid4(),
+        user_id=user_id,
+        family_id=family_id,
+        token_hash=hash_refresh_token(refresh_token),
+        created_at=now,
+        family_created_at=now,
+        last_used_at=now,
+    )

python_platform/identity/contracts.py

@@ -0,0 +1,283 @@
+"""Identity 的 HTTP/Application contracts、持久化值与 Host keyring Options。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Annotated, Protocol
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator, model_validator
+
+from ..application_services import ApplicationServiceContract
+from ..authorization import (
+    CurrentUser,
+    PermissionName,
+    RolePermissionVersion,
+)
+from ..options import BaseOptions
+
+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]
+    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(BaseModel):
+    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)]
+
+
+class CreateRoleCommand(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: Annotated[str, Field(min_length=1, max_length=120)]
+
+
+class SetUserRolesCommand(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    role_ids: tuple[UUID, ...]
+
+
+class SetRolePermissionsCommand(BaseModel):
+    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
+
+
+@dataclass(frozen=True, slots=True)
+class UserView:
+    user_id: UUID
+    username: str
+    is_active: bool
+    role_ids: tuple[UUID, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RoleView:
+    role_id: UUID
+    name: str
+    permissions: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentUserView:
+    user_id: UUID
+    session_id: UUID
+    username: str
+
+
+@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
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityRole:
+    role_id: UUID
+    name: str
+    normalized_name: str
+    permission_version: int
+
+
+@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 list_users(self) -> tuple[UserView, ...]: ...
+
+    async def create_role(self, role: IdentityRole) -> None: ...
+
+    async def find_role_by_normalized_name(self, normalized_name: str) -> IdentityRole | None: ...
+
+    async def list_roles(self) -> tuple[RoleView, ...]: ...
+
+    async def set_user_roles(self, user_id: UUID, role_ids: tuple[UUID, ...]) -> None: ...
+
+    async def set_role_permissions(self, role_id: UUID, permissions: tuple[str, ...]) -> None: ...
+
+
+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: ...
+
+
+class AuthenticationApplicationService(ApplicationServiceContract, Protocol):
+    async def login(self, command: LoginCommand) -> TokenPair: ...
+
+    async def refresh(self, command: RefreshTokenCommand) -> TokenPair: ...
+
+    async def revoke(self, command: RevokeTokenCommand) -> None: ...
+
+    async def me(self) -> CurrentUserView: ...
+
+
+class IdentityManagementApplicationService(ApplicationServiceContract, Protocol):
+    async def create_user(self, command: CreateUserCommand) -> UserView: ...
+
+    async def get_users(self) -> tuple[UserView, ...]: ...
+
+    async def create_role(self, command: CreateRoleCommand) -> RoleView: ...
+
+    async def get_roles(self) -> tuple[RoleView, ...]: ...
+
+    async def set_user_roles(self, user_id: UUID, command: SetUserRolesCommand) -> None: ...
+
+    async def set_role_permissions(
+        self, role_id: UUID, command: SetRolePermissionsCommand
+    ) -> None: ...
+
+
+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

python_platform/identity/errors.py

@@ -0,0 +1,28 @@
+"""Identity 对外只暴露静态错误类型，不泄漏凭据、Token 或数据库文本。"""
+
+from __future__ import annotations
+
+from ..authorization import UnauthenticatedError
+from ..errors.base import FrameworkError, ResourceConflictError, ResourceNotFoundError
+
+
+class IdentityDefinitionError(FrameworkError):
+    def __init__(self, *, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"Invalid Identity configuration: {reason}")
+
+
+class InvalidCredentialsError(UnauthenticatedError):
+    """用户名不存在、密码错误、锁定和 Token 无效共享同一公开失败。"""
+
+
+class IdentityConflictError(ResourceConflictError):
+    def __init__(self, *, resource: str) -> None:
+        self.resource = resource
+        super().__init__(f"Identity resource {resource!r} already exists")
+
+
+class IdentityResourceNotFoundError(ResourceNotFoundError):
+    def __init__(self, *, resource: str) -> None:
+        self.resource = resource
+        super().__init__(f"Identity resource {resource!r} was not found")

python_platform/identity/http_api.py

@@ -0,0 +1,90 @@
+"""Identity Application Services 的标准 HTTP 路径。"""
+
+from __future__ import annotations
+
+from ..fastapi import ApplicationServiceRouteOverride, exposes_application_services
+from ..modularity import AppModule
+from .contracts import AuthenticationApplicationService, IdentityManagementApplicationService
+from .module import IdentityModule
+
+
+@exposes_application_services(
+    IdentityModule,
+    root_path="identity",
+    overrides=(
+        ApplicationServiceRouteOverride(
+            AuthenticationApplicationService,
+            method=AuthenticationApplicationService.login,
+            path="/api/auth/login",
+            verb="POST",
+            operation_id="identity_login",
+        ),
+        ApplicationServiceRouteOverride(
+            AuthenticationApplicationService,
+            method=AuthenticationApplicationService.refresh,
+            path="/api/auth/refresh",
+            verb="POST",
+            operation_id="identity_refresh",
+        ),
+        ApplicationServiceRouteOverride(
+            AuthenticationApplicationService,
+            method=AuthenticationApplicationService.revoke,
+            path="/api/auth/revoke",
+            verb="POST",
+            operation_id="identity_revoke",
+        ),
+        ApplicationServiceRouteOverride(
+            AuthenticationApplicationService,
+            method=AuthenticationApplicationService.me,
+            path="/api/auth/me",
+            verb="GET",
+            operation_id="identity_me",
+        ),
+        ApplicationServiceRouteOverride(
+            IdentityManagementApplicationService,
+            method=IdentityManagementApplicationService.create_user,
+            path="/api/identity/users",
+            verb="POST",
+            status_code=201,
+            operation_id="identity_create_user",
+        ),
+        ApplicationServiceRouteOverride(
+            IdentityManagementApplicationService,
+            method=IdentityManagementApplicationService.get_users,
+            path="/api/identity/users",
+            verb="GET",
+            operation_id="identity_get_users",
+        ),
+        ApplicationServiceRouteOverride(
+            IdentityManagementApplicationService,
+            method=IdentityManagementApplicationService.create_role,
+            path="/api/identity/roles",
+            verb="POST",
+            status_code=201,
+            operation_id="identity_create_role",
+        ),
+        ApplicationServiceRouteOverride(
+            IdentityManagementApplicationService,
+            method=IdentityManagementApplicationService.get_roles,
+            path="/api/identity/roles",
+            verb="GET",
+            operation_id="identity_get_roles",
+        ),
+        ApplicationServiceRouteOverride(
+            IdentityManagementApplicationService,
+            method=IdentityManagementApplicationService.set_user_roles,
+            path="/api/identity/users/{user_id}/roles",
+            verb="PUT",
+            operation_id="identity_set_user_roles",
+        ),
+        ApplicationServiceRouteOverride(
+            IdentityManagementApplicationService,
+            method=IdentityManagementApplicationService.set_role_permissions,
+            path="/api/identity/roles/{role_id}/permissions",
+            verb="PUT",
+            operation_id="identity_set_role_permissions",
+        ),
+    ),
+)
+class IdentityHttpApiModule(AppModule):
+    dependencies = (IdentityModule,)