python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/identity/module.py

@@ -0,0 +1,49 @@
+"""Provider-neutral Identity Module 只注册正式 contract 与 security services。"""
+
+from __future__ import annotations
+
+from dishka import Provider, Scope
+
+from ..authorization import AccessTokenAuthenticator, PermissionChecker
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from .contracts import (
+    IdentityOptions,
+)
+from .passwords import PasswordHasher
+from .services import (
+    IDENTITY_PERMISSION_CACHE,
+    IdentityAuthenticator,
+    IdentityPermissionChecker,
+)
+from .tokens import JwtTokenService
+
+
+class IdentityModule(AppModule):
+    scan_packages = (
+        "python_ddd_framework.identity.application",
+        "python_ddd_framework.identity.permissions",
+    )
+
+    cache_definitions = (IDENTITY_PERMISSION_CACHE,)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure(
+            IdentityOptions,
+            section="identity",
+            secret_paths=frozenset({"keys", "seed_admin_password"}),
+        )
+        provider = Provider()
+        provider.provide(PasswordHasher, provides=PasswordHasher, scope=Scope.APP)
+        provider.provide(JwtTokenService, provides=JwtTokenService, scope=Scope.APP)
+        provider.provide(
+            IdentityAuthenticator,
+            provides=AccessTokenAuthenticator,
+            scope=Scope.APP,
+        )
+        provider.provide(
+            IdentityPermissionChecker,
+            provides=PermissionChecker,
+            scope=Scope.APP,
+        )
+        context.services.contribute(provider, reason="Identity security services")

python_ddd_framework/identity/passwords.py

@@ -0,0 +1,34 @@
+"""pwdlib Argon2id boundary；昂贵 hash/verify 不阻塞 asyncio event loop。"""
+
+from __future__ import annotations
+
+import asyncio
+
+from pwdlib import PasswordHash
+
+_DUMMY_HASH = (
+    "$argon2id$v=19$m=65536,t=3,p=4$VyPuPaiooyVPpvuUem+SEA$"
+    "FGOxAPGfz6q2biOigVe+t5G92Au3TgjT/eOEKxT6+Mk"
+)
+
+
+class PasswordHasher:
+    __slots__ = ("_password_hash",)
+
+    def __init__(self) -> None:
+        self._password_hash = PasswordHash.recommended()
+
+    async def hash(self, password: str) -> str:
+        return await asyncio.to_thread(self._password_hash.hash, password)
+
+    async def verify(self, password: str, password_hash: str | None) -> tuple[bool, str | None]:
+        selected_hash = password_hash if password_hash is not None else _DUMMY_HASH
+        try:
+            return await asyncio.to_thread(
+                self._password_hash.verify_and_update,
+                password,
+                selected_hash,
+            )
+        except Exception:
+            # 持久化 hash 损坏与错误密码共享失败语义，且绝不回显 hash/parser 文本。
+            return False, None

python_ddd_framework/identity/permissions.py

@@ -0,0 +1,14 @@
+"""identity 权限定义；持久化名称继续来自所属正式契约。"""
+
+from ..authorization import (
+    PermissionDefinition,
+    PermissionDefinitionContext,
+    PermissionDefinitionProvider,
+)
+from .contracts import IDENTITY_ROLES_MANAGE, IDENTITY_USERS_MANAGE
+
+
+class IdentityPermissionDefinitionProvider(PermissionDefinitionProvider):
+    def define(self, context: PermissionDefinitionContext) -> None:
+        context.add(PermissionDefinition(IDENTITY_USERS_MANAGE, "Manage identity users"))
+        context.add(PermissionDefinition(IDENTITY_ROLES_MANAGE, "Manage identity roles"))

python_ddd_framework/identity/services.py

@@ -0,0 +1,108 @@
+"""Access token authentication 与 version-bound permission cache orchestration。"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime, timedelta
+
+from dishka import AsyncContainer
+from dishka.exceptions import NoFactoryError
+from pydantic import BaseModel, ConfigDict
+
+from ..authorization import CurrentUser, PermissionCatalog, PermissionChecker, PermissionName
+from ..caching import CacheDefinition, DistributedCache, DistributedCacheError
+from .contracts import IdentityAccessStore
+from .errors import InvalidCredentialsError
+from .tokens import JwtTokenService
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class PermissionCacheEntry(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    permissions: tuple[str, ...]
+
+
+IDENTITY_PERMISSION_CACHE = CacheDefinition(
+    "identity.permissions",
+    PermissionCacheEntry,
+    ttl=timedelta(minutes=5),
+)
+
+
+class IdentityAuthenticator:
+    __slots__ = ("_access", "_tokens")
+
+    def __init__(self, tokens: JwtTokenService, access: IdentityAccessStore) -> None:
+        self._tokens = tokens
+        self._access = access
+
+    async def authenticate_access_token(self, token: str) -> CurrentUser:
+        claims = self._tokens.verify(token)
+        current_user = await self._access.load_current_user(
+            claims.user_id,
+            claims.session_id,
+            datetime.now(UTC),
+        )
+        if current_user is None:
+            raise InvalidCredentialsError
+        return current_user
+
+
+class IdentityPermissionChecker(PermissionChecker):
+    __slots__ = ("_access", "_catalog", "_container")
+
+    def __init__(
+        self,
+        access: IdentityAccessStore,
+        catalog: PermissionCatalog,
+        container: AsyncContainer,
+    ) -> None:
+        self._access = access
+        self._catalog = catalog
+        self._container = container
+
+    async def is_granted(self, user: CurrentUser, permission: PermissionName) -> bool:
+        if not user.is_authenticated or permission not in self._catalog:
+            return False
+        cache = await self._optional_cache()
+        cache_key = _permission_cache_key(user, self._catalog.fingerprint)
+        if cache is not None:
+            try:
+                cached = await cache.get(IDENTITY_PERMISSION_CACHE, cache_key)
+            except DistributedCacheError:
+                cached = None
+                _LOGGER.warning(
+                    "permission cache read failed; falling back to authoritative database",
+                    extra={"cache": IDENTITY_PERMISSION_CACHE.name},
+                )
+            if cached is not None:
+                return permission.value in cached.permissions
+
+        permissions = await self._access.permissions_for_roles(user.role_versions)
+        if cache is not None:
+            try:
+                await cache.set(
+                    IDENTITY_PERMISSION_CACHE,
+                    cache_key,
+                    PermissionCacheEntry(permissions=tuple(sorted(permissions))),
+                )
+            except DistributedCacheError:
+                _LOGGER.warning(
+                    "permission cache write failed; database result remains authoritative",
+                    extra={"cache": IDENTITY_PERMISSION_CACHE.name},
+                )
+        return permission.value in permissions
+
+    async def _optional_cache(self) -> DistributedCache | None:
+        try:
+            return await self._container.get(DistributedCache)
+        except NoFactoryError:
+            return None
+
+
+def _permission_cache_key(user: CurrentUser, catalog_fingerprint: str) -> str:
+    role_versions = ",".join(f"{item.role_id.hex}.{item.version}" for item in user.role_versions)
+    assert user.user_id is not None
+    return f"{catalog_fingerprint}:{user.user_id.hex}:{user.permission_version}:{role_versions}"

python_ddd_framework/identity/sqlalchemy/__init__.py

@@ -0,0 +1,5 @@
+"""Identity 的 SQLAlchemy/PostgreSQL provider。"""
+
+from .module import SqlAlchemyIdentityModule
+
+__all__ = ("SqlAlchemyIdentityModule",)

python_ddd_framework/identity/sqlalchemy/migrations/0001_identity.py

@@ -0,0 +1,143 @@
+"""Create the independent framework identity migration branch."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "identity_0001"
+down_revision = None
+branch_labels = ("identity",)
+depends_on = None
+
+
+def _audit_columns() -> tuple[sa.Column[Any], ...]:
+    return (
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("created_by", sa.Uuid(), nullable=True),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("updated_by", sa.Uuid(), nullable=True),
+    )
+
+
+def _soft_delete_columns() -> tuple[sa.Column[Any], ...]:
+    return (
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("deleted_by", sa.Uuid(), nullable=True),
+    )
+
+
+def upgrade() -> None:
+    op.create_table(
+        "identity_users",
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("username", sa.String(length=120), nullable=False),
+        sa.Column("normalized_username", sa.String(length=120), nullable=False),
+        sa.Column("password_hash", sa.String(length=512), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("failed_access_count", sa.Integer(), nullable=False),
+        sa.Column("lockout_end", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("permission_version", sa.BigInteger(), nullable=False),
+        *_audit_columns(),
+        *_soft_delete_columns(),
+        sa.PrimaryKeyConstraint("user_id"),
+    )
+    op.create_index(
+        "ix_identity_users_normalized_username",
+        "identity_users",
+        ["normalized_username"],
+        unique=True,
+    )
+    op.create_table(
+        "identity_roles",
+        sa.Column("role_id", sa.Uuid(), nullable=False),
+        sa.Column("name", sa.String(length=120), nullable=False),
+        sa.Column("normalized_name", sa.String(length=120), nullable=False),
+        sa.Column("permission_version", sa.BigInteger(), nullable=False),
+        *_audit_columns(),
+        *_soft_delete_columns(),
+        sa.PrimaryKeyConstraint("role_id"),
+    )
+    op.create_index(
+        "ix_identity_roles_normalized_name",
+        "identity_roles",
+        ["normalized_name"],
+        unique=True,
+    )
+    op.create_table(
+        "identity_user_roles",
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("role_id", sa.Uuid(), nullable=False),
+        *_audit_columns(),
+        sa.ForeignKeyConstraint(["role_id"], ["identity_roles.role_id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["identity_users.user_id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("user_id", "role_id"),
+    )
+    op.create_table(
+        "identity_role_permissions",
+        sa.Column("role_id", sa.Uuid(), nullable=False),
+        sa.Column("permission_name", sa.String(length=200), nullable=False),
+        *_audit_columns(),
+        sa.ForeignKeyConstraint(["role_id"], ["identity_roles.role_id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("role_id", "permission_name"),
+    )
+    op.create_table(
+        "identity_refresh_sessions",
+        sa.Column("session_id", sa.Uuid(), nullable=False),
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("family_id", sa.Uuid(), nullable=False),
+        sa.Column("token_hash", sa.String(length=64), nullable=False),
+        sa.Column("family_created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("last_used_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("replaced_by_session_id", sa.Uuid(), nullable=True),
+        *_audit_columns(),
+        sa.ForeignKeyConstraint(["user_id"], ["identity_users.user_id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("session_id"),
+    )
+    op.create_index(
+        "ix_identity_refresh_sessions_user_id",
+        "identity_refresh_sessions",
+        ["user_id"],
+    )
+    op.create_index(
+        "ix_identity_refresh_sessions_family_id",
+        "identity_refresh_sessions",
+        ["family_id"],
+    )
+    op.create_index(
+        "ix_identity_refresh_sessions_token_hash",
+        "identity_refresh_sessions",
+        ["token_hash"],
+        unique=True,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_identity_refresh_sessions_token_hash",
+        table_name="identity_refresh_sessions",
+    )
+    op.drop_index(
+        "ix_identity_refresh_sessions_family_id",
+        table_name="identity_refresh_sessions",
+    )
+    op.drop_index(
+        "ix_identity_refresh_sessions_user_id",
+        table_name="identity_refresh_sessions",
+    )
+    op.drop_table("identity_refresh_sessions")
+    op.drop_table("identity_role_permissions")
+    op.drop_table("identity_user_roles")
+    op.drop_index(
+        "ix_identity_roles_normalized_name",
+        table_name="identity_roles",
+    )
+    op.drop_table("identity_roles")
+    op.drop_index(
+        "ix_identity_users_normalized_username",
+        table_name="identity_users",
+    )
+    op.drop_table("identity_users")

python_ddd_framework/identity/sqlalchemy/migrations/0002_physical_delete.py

@@ -0,0 +1,42 @@
+"""退出软删除，升级只接受已经人工处理完历史软删除记录的数据库。"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+from python_ddd_framework.sqlalchemy.errors import SoftDeleteMigrationBlockedError
+
+revision = "identity_0002"
+down_revision = "identity_0001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    connection = op.get_bind()
+    tables = ("identity_users", "identity_roles")
+    # 检查和 DDL 共享事务锁，旧进程不能在检查后插入新的软删除记录。
+    for name in tables:
+        connection.execute(sa.text(f"LOCK TABLE {name} IN ACCESS EXCLUSIVE MODE"))
+    affected = tuple(
+        (
+            name,
+            int(
+                connection.scalar(
+                    sa.text(f"SELECT count(*) FROM {name} WHERE deleted_at IS NOT NULL")
+                )
+                or 0
+            ),
+        )
+        for name in tables
+    )
+    if any(count for _, count in affected):
+        raise SoftDeleteMigrationBlockedError(tuple(item for item in affected if item[1]))
+    for name in tables:
+        op.drop_column(name, "deleted_at")
+        op.drop_column(name, "deleted_by")
+
+
+def downgrade() -> None:
+    raise RuntimeError("physical deletion cannot restore historical deleted records")

python_ddd_framework/identity/sqlalchemy/migrations/__init__.py

@@ -0,0 +1 @@
+"""Framework identity Alembic branch。"""

python_ddd_framework/identity/sqlalchemy/models.py

@@ -0,0 +1,85 @@
+"""Identity rows 与独立 metadata owner。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from sqlalchemy import BigInteger, Boolean, DateTime, ForeignKey, Integer, String, Uuid
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from ...sqlalchemy import AuditedEntityMixin
+
+
+class IdentityBase(DeclarativeBase):
+    pass
+
+
+class UserRow(AuditedEntityMixin, IdentityBase):
+    __tablename__ = "identity_users"
+
+    user_id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
+    username: Mapped[str] = mapped_column(String(120), nullable=False)
+    normalized_username: Mapped[str] = mapped_column(
+        String(120), nullable=False, unique=True, index=True
+    )
+    password_hash: Mapped[str] = mapped_column(String(512), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    failed_access_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    lockout_end: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    permission_version: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+
+
+class RoleRow(AuditedEntityMixin, IdentityBase):
+    __tablename__ = "identity_roles"
+
+    role_id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
+    name: Mapped[str] = mapped_column(String(120), nullable=False)
+    normalized_name: Mapped[str] = mapped_column(
+        String(120), nullable=False, unique=True, index=True
+    )
+    permission_version: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+
+
+class UserRoleRow(AuditedEntityMixin, IdentityBase):
+    __tablename__ = "identity_user_roles"
+
+    user_id: Mapped[UUID] = mapped_column(
+        Uuid,
+        ForeignKey("identity_users.user_id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    role_id: Mapped[UUID] = mapped_column(
+        Uuid,
+        ForeignKey("identity_roles.role_id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+
+
+class RolePermissionRow(AuditedEntityMixin, IdentityBase):
+    __tablename__ = "identity_role_permissions"
+
+    role_id: Mapped[UUID] = mapped_column(
+        Uuid,
+        ForeignKey("identity_roles.role_id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    permission_name: Mapped[str] = mapped_column(String(200), primary_key=True)
+
+
+class RefreshSessionRow(AuditedEntityMixin, IdentityBase):
+    __tablename__ = "identity_refresh_sessions"
+
+    session_id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
+    user_id: Mapped[UUID] = mapped_column(
+        Uuid,
+        ForeignKey("identity_users.user_id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    family_id: Mapped[UUID] = mapped_column(Uuid, nullable=False, index=True)
+    token_hash: Mapped[str] = mapped_column(String(64), nullable=False, unique=True, index=True)
+    family_created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    last_used_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    replaced_by_session_id: Mapped[UUID | None] = mapped_column(Uuid, nullable=True)

python_ddd_framework/identity/sqlalchemy/module.py

@@ -0,0 +1,62 @@
+"""Host 显式选择的 Identity SQLAlchemy provider Module。"""
+
+from __future__ import annotations
+
+from dishka import Provider, Scope
+
+from ...lifecycle import ConfigureContext
+from ...modularity import AppModule
+from ...sqlalchemy import (
+    SqlAlchemyModelRegistration,
+    SqlAlchemyPersistenceModule,
+    contributes_sqlalchemy_models,
+)
+from ..contracts import (
+    IdentityAccessStore,
+    IdentityLoginStore,
+    IdentityRepository,
+    RefreshSessionStore,
+)
+from ..module import IdentityModule
+from .models import IdentityBase
+from .stores import (
+    SqlAlchemyIdentityAccessStore,
+    SqlAlchemyIdentityLoginStore,
+    SqlAlchemyIdentityRepository,
+    SqlAlchemyRefreshSessionStore,
+)
+
+
+@contributes_sqlalchemy_models(
+    SqlAlchemyModelRegistration(
+        metadata=IdentityBase.metadata,
+        migrations_package="python_ddd_framework.identity.sqlalchemy.migrations",
+        branch_label="identity",
+    )
+)
+class SqlAlchemyIdentityModule(AppModule):
+    dependencies = (IdentityModule, SqlAlchemyPersistenceModule)
+
+    def configure(self, context: ConfigureContext) -> None:
+        provider = Provider()
+        provider.provide(
+            SqlAlchemyIdentityRepository,
+            provides=IdentityRepository,
+            scope=Scope.REQUEST,
+        )
+        provider.provide(
+            SqlAlchemyIdentityAccessStore,
+            provides=IdentityAccessStore,
+            scope=Scope.APP,
+        )
+        provider.provide(
+            SqlAlchemyIdentityLoginStore,
+            provides=IdentityLoginStore,
+            scope=Scope.APP,
+        )
+        provider.provide(
+            SqlAlchemyRefreshSessionStore,
+            provides=RefreshSessionStore,
+            scope=Scope.APP,
+        )
+        context.services.contribute(provider, reason="Identity SQLAlchemy providers")