python-platform 0.1.1__py3-none-any.whl

python_platform/identity/sqlalchemy/stores.py

@@ -0,0 +1,526 @@
+"""Identity repository、request access check 与独立 refresh/login 事务。"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from hashlib import blake2b
+from uuid import UUID
+
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...authorization import CurrentUser, RolePermissionVersion
+from ...sqlalchemy import PlatformAsyncSession, SqlAlchemySessionProvider
+from ...sqlalchemy.runtime import _SqlAlchemyEngineRegistry
+from ..contracts import (
+    IdentityRole,
+    IdentityUser,
+    RefreshRotationResult,
+    RefreshRotationStatus,
+    RefreshSession,
+    RoleView,
+    UserView,
+)
+from ..errors import IdentityConflictError, IdentityResourceNotFoundError
+from ..tokens import REFRESH_ABSOLUTE_LIFETIME, REFRESH_INACTIVITY_LIFETIME
+from .models import (
+    RefreshSessionRow,
+    RolePermissionRow,
+    RoleRow,
+    UserRoleRow,
+    UserRow,
+)
+
+_REFRESH_FAMILY_LOCK_PERSON = b"pyplat.rfam.v1"
+
+
+class SqlAlchemyIdentityRepository:
+    __slots__ = ("_provider",)
+
+    def __init__(self, provider: SqlAlchemySessionProvider) -> None:
+        self._provider = provider
+
+    async def find_user_by_normalized_username(
+        self,
+        normalized_username: str,
+    ) -> IdentityUser | None:
+        async with self._provider.operation("find_user_by_normalized_username"):
+            session = await self._provider.get_session()
+            statement = select(UserRow).where(UserRow.normalized_username == normalized_username)
+            row = await session.scalar(statement)
+            return None if row is None else _user_value(row)
+
+    async def create_user(self, user: IdentityUser) -> None:
+        async with self._provider.operation("create_user"):
+            session = await self._provider.get_session()
+            session.add(
+                UserRow(
+                    user_id=user.user_id,
+                    username=user.username,
+                    normalized_username=user.normalized_username,
+                    password_hash=user.password_hash,
+                    is_active=user.is_active,
+                    failed_access_count=user.failed_access_count,
+                    lockout_end=user.lockout_end,
+                    permission_version=user.permission_version,
+                )
+            )
+            await self._flush_unique("user")
+
+    async def list_users(self) -> tuple[UserView, ...]:
+        async with self._provider.operation("list_users"):
+            session = await self._provider.get_session()
+            rows = tuple(
+                (await session.scalars(select(UserRow).order_by(UserRow.normalized_username))).all()
+            )
+            role_rows = (
+                await session.execute(
+                    select(UserRoleRow.user_id, UserRoleRow.role_id).order_by(
+                        UserRoleRow.user_id, UserRoleRow.role_id
+                    )
+                )
+            ).all()
+            roles_by_user: dict[UUID, list[UUID]] = {}
+            for user_id, role_id in role_rows:
+                roles_by_user.setdefault(user_id, []).append(role_id)
+            return tuple(
+                UserView(
+                    user_id=row.user_id,
+                    username=row.username,
+                    is_active=row.is_active,
+                    role_ids=tuple(roles_by_user.get(row.user_id, ())),
+                )
+                for row in rows
+            )
+
+    async def create_role(self, role: IdentityRole) -> None:
+        async with self._provider.operation("create_role"):
+            session = await self._provider.get_session()
+            session.add(
+                RoleRow(
+                    role_id=role.role_id,
+                    name=role.name,
+                    normalized_name=role.normalized_name,
+                    permission_version=role.permission_version,
+                )
+            )
+            await self._flush_unique("role")
+
+    async def find_role_by_normalized_name(self, normalized_name: str) -> IdentityRole | None:
+        async with self._provider.operation("find_role_by_normalized_name"):
+            session = await self._provider.get_session()
+            row = await session.scalar(
+                select(RoleRow).where(RoleRow.normalized_name == normalized_name)
+            )
+            return None if row is None else _role_value(row)
+
+    async def list_roles(self) -> tuple[RoleView, ...]:
+        async with self._provider.operation("list_roles"):
+            session = await self._provider.get_session()
+            roles = tuple(
+                (await session.scalars(select(RoleRow).order_by(RoleRow.normalized_name))).all()
+            )
+            permission_rows = (
+                await session.execute(
+                    select(RolePermissionRow.role_id, RolePermissionRow.permission_name).order_by(
+                        RolePermissionRow.role_id, RolePermissionRow.permission_name
+                    )
+                )
+            ).all()
+            permissions_by_role: dict[UUID, list[str]] = {}
+            for role_id, permission_name in permission_rows:
+                permissions_by_role.setdefault(role_id, []).append(permission_name)
+            return tuple(
+                RoleView(
+                    role_id=row.role_id,
+                    name=row.name,
+                    permissions=tuple(permissions_by_role.get(row.role_id, ())),
+                )
+                for row in roles
+            )
+
+    async def set_user_roles(self, user_id: UUID, role_ids: tuple[UUID, ...]) -> None:
+        async with self._provider.operation("set_user_roles"):
+            session = await self._provider.get_session()
+            user = await self._require_user(user_id, for_update=True)
+            requested = frozenset(role_ids)
+            roles = tuple(
+                (
+                    await session.scalars(
+                        select(RoleRow).where(RoleRow.role_id.in_(requested)).with_for_update()
+                    )
+                ).all()
+            )
+            if len(roles) != len(requested):
+                raise IdentityResourceNotFoundError(resource="role")
+            existing = tuple(
+                (
+                    await session.scalars(
+                        select(UserRoleRow).where(UserRoleRow.user_id == user_id).with_for_update()
+                    )
+                ).all()
+            )
+            current = frozenset(item.role_id for item in existing)
+            if current == requested:
+                return
+            for item in existing:
+                if item.role_id not in requested:
+                    await session.delete(item)
+            for role_id in sorted(requested - current):
+                session.add(UserRoleRow(user_id=user_id, role_id=role_id))
+            user.permission_version += 1
+
+    async def set_role_permissions(self, role_id: UUID, permissions: tuple[str, ...]) -> None:
+        async with self._provider.operation("set_role_permissions"):
+            session = await self._provider.get_session()
+            role = await self._require_role(role_id, for_update=True)
+            requested = frozenset(permissions)
+            existing = tuple(
+                (
+                    await session.scalars(
+                        select(RolePermissionRow)
+                        .where(RolePermissionRow.role_id == role_id)
+                        .with_for_update()
+                    )
+                ).all()
+            )
+            current = frozenset(item.permission_name for item in existing)
+            if current == requested:
+                return
+            for item in existing:
+                if item.permission_name not in requested:
+                    await session.delete(item)
+            for permission in sorted(requested - current):
+                session.add(RolePermissionRow(role_id=role_id, permission_name=permission))
+            role.permission_version += 1
+
+    async def _require_user(self, user_id: UUID, *, for_update: bool) -> UserRow:
+        session = await self._provider.get_session()
+        statement = select(UserRow).where(UserRow.user_id == user_id)
+        if for_update:
+            statement = statement.with_for_update()
+        row = await session.scalar(statement)
+        if row is None:
+            raise IdentityResourceNotFoundError(resource="user")
+        return row
+
+    async def _require_role(self, role_id: UUID, *, for_update: bool) -> RoleRow:
+        session = await self._provider.get_session()
+        statement = select(RoleRow).where(RoleRow.role_id == role_id)
+        if for_update:
+            statement = statement.with_for_update()
+        row = await session.scalar(statement)
+        if row is None:
+            raise IdentityResourceNotFoundError(resource="role")
+        return row
+
+    async def _flush_unique(self, resource: str) -> None:
+        session = await self._provider.get_session()
+        try:
+            await session.flush()
+        except IntegrityError:
+            raise IdentityConflictError(resource=resource) from None
+
+
+class SqlAlchemyIdentityAccessStore:
+    __slots__ = ("_engines",)
+
+    def __init__(self, engines: _SqlAlchemyEngineRegistry) -> None:
+        self._engines = engines
+
+    async def load_current_user(
+        self,
+        user_id: UUID,
+        session_id: UUID,
+        now: datetime,
+    ) -> CurrentUser | None:
+        async with self._session() as session:
+            user = await session.scalar(
+                select(UserRow).where(UserRow.user_id == user_id, UserRow.is_active.is_(True))
+            )
+            refresh = await session.scalar(
+                select(RefreshSessionRow).where(
+                    RefreshSessionRow.session_id == session_id,
+                    RefreshSessionRow.user_id == user_id,
+                )
+            )
+            if user is None or refresh is None or not _session_is_active(refresh, now):
+                return None
+            role_rows = (
+                await session.execute(
+                    select(RoleRow.role_id, RoleRow.permission_version)
+                    .join(UserRoleRow, UserRoleRow.role_id == RoleRow.role_id)
+                    .where(UserRoleRow.user_id == user_id)
+                    .order_by(RoleRow.role_id)
+                )
+            ).all()
+            return CurrentUser(
+                user_id=user.user_id,
+                session_id=refresh.session_id,
+                username=user.username,
+                permission_version=user.permission_version,
+                role_versions=tuple(
+                    RolePermissionVersion(role_id=role_id, version=version)
+                    for role_id, version in role_rows
+                ),
+            )
+
+    async def permissions_for_roles(
+        self,
+        role_versions: tuple[RolePermissionVersion, ...],
+    ) -> frozenset[str]:
+        if not role_versions:
+            return frozenset()
+        role_ids = tuple(item.role_id for item in role_versions)
+        expected = {item.role_id: item.version for item in role_versions}
+        async with self._session() as session:
+            actual_rows = (
+                await session.execute(
+                    select(RoleRow.role_id, RoleRow.permission_version).where(
+                        RoleRow.role_id.in_(role_ids)
+                    )
+                )
+            ).all()
+            actual: dict[UUID, int] = dict((role_id, version) for role_id, version in actual_rows)
+            # Cache miss 时仍重新核对版本；并发权限修改不能把旧 allow 写进新版本 key。
+            if actual != expected:
+                return frozenset()
+            permissions = (
+                await session.scalars(
+                    select(RolePermissionRow.permission_name).where(
+                        RolePermissionRow.role_id.in_(role_ids)
+                    )
+                )
+            ).all()
+            return frozenset(permissions)
+
+    def _session(self) -> PlatformAsyncSession:
+        return PlatformAsyncSession(self._engines.get("default"), expire_on_commit=False)
+
+
+class SqlAlchemyIdentityLoginStore:
+    __slots__ = ("_engines",)
+
+    def __init__(self, engines: _SqlAlchemyEngineRegistry) -> None:
+        self._engines = engines
+
+    async def find_user(self, normalized_username: str) -> IdentityUser | None:
+        async with self._session() as session:
+            row = await session.scalar(
+                select(UserRow).where(UserRow.normalized_username == normalized_username)
+            )
+            return None if row is None else _user_value(row)
+
+    async def record_failure(
+        self,
+        user_id: UUID,
+        *,
+        now: datetime,
+        attempt_limit: int,
+        lockout_duration_seconds: int,
+    ) -> None:
+        async with self._session() as session, session.begin():
+            row = await session.scalar(
+                select(UserRow).where(UserRow.user_id == user_id).with_for_update()
+            )
+            if row is None or not row.is_active:
+                return
+            count = (
+                0
+                if row.lockout_end is not None and row.lockout_end <= now
+                else row.failed_access_count
+            )
+            count += 1
+            row.failed_access_count = count
+            row.lockout_end = (
+                now + timedelta(seconds=lockout_duration_seconds)
+                if count >= attempt_limit
+                else None
+            )
+
+    async def complete_success(
+        self,
+        user_id: UUID,
+        *,
+        expected_password_hash: str,
+        updated_password_hash: str | None,
+        session: RefreshSession,
+        now: datetime,
+    ) -> bool:
+        async with self._session() as database, database.begin():
+            row = await database.scalar(
+                select(UserRow).where(UserRow.user_id == user_id).with_for_update()
+            )
+            if (
+                row is None
+                or not row.is_active
+                or row.password_hash != expected_password_hash
+                or (row.lockout_end is not None and row.lockout_end > now)
+            ):
+                return False
+            row.failed_access_count = 0
+            row.lockout_end = None
+            if updated_password_hash is not None:
+                row.password_hash = updated_password_hash
+            database.add(_refresh_row(session))
+            return True
+
+    def _session(self) -> PlatformAsyncSession:
+        return PlatformAsyncSession(self._engines.get("default"), expire_on_commit=False)
+
+
+class SqlAlchemyRefreshSessionStore:
+    __slots__ = ("_engines",)
+
+    def __init__(self, engines: _SqlAlchemyEngineRegistry) -> None:
+        self._engines = engines
+
+    async def rotate(
+        self,
+        token_hash: str,
+        *,
+        replacement_id: UUID,
+        replacement_hash: str,
+        now: datetime,
+    ) -> RefreshRotationResult:
+        async with self._session() as session, session.begin():
+            family_id = await session.scalar(
+                select(RefreshSessionRow.family_id).where(
+                    RefreshSessionRow.token_hash == token_hash
+                )
+            )
+            if family_id is None:
+                return RefreshRotationResult(RefreshRotationStatus.NOT_FOUND, None)
+            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 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)
+            if not _session_is_active(current, now):
+                await _revoke_family(session, current.family_id, now=now)
+                return RefreshRotationResult(RefreshRotationStatus.EXPIRED, None)
+
+            replacement = RefreshSession(
+                session_id=replacement_id,
+                user_id=current.user_id,
+                family_id=current.family_id,
+                token_hash=replacement_hash,
+                created_at=now,
+                family_created_at=current.family_created_at,
+                last_used_at=now,
+            )
+            current.revoked_at = now
+            current.replaced_by_session_id = replacement_id
+            current.last_used_at = now
+            session.add(_refresh_row(replacement))
+            return RefreshRotationResult(RefreshRotationStatus.ROTATED, replacement)
+
+    async def revoke(self, token_hash: str, *, now: datetime) -> None:
+        async with self._session() as session, session.begin():
+            family_id = await session.scalar(
+                select(RefreshSessionRow.family_id).where(
+                    RefreshSessionRow.token_hash == token_hash
+                )
+            )
+            if family_id is None:
+                return
+            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
+                await _revoke_family(session, current.family_id, now=now)
+
+    def _session(self) -> PlatformAsyncSession:
+        return PlatformAsyncSession(self._engines.get("default"), expire_on_commit=False)
+
+
+async def _revoke_family(
+    session: AsyncSession,
+    family_id: UUID,
+    *,
+    now: datetime,
+) -> None:
+    rows = tuple(
+        (
+            await session.scalars(
+                select(RefreshSessionRow)
+                .where(RefreshSessionRow.family_id == family_id)
+                .with_for_update()
+            )
+        ).all()
+    )
+    for row in rows:
+        if row.revoked_at is None:
+            row.revoked_at = now
+
+
+async def _lock_refresh_family(session: AsyncSession, family_id: UUID) -> None:
+    # family 没有可锁的稳定 parent row；transaction advisory lock 在同一短事务内提供
+    # family -> token/family rows 的统一顺序，并随 commit/rollback 自动释放。
+    await session.scalar(select(func.pg_advisory_xact_lock(_refresh_family_lock_key(family_id))))
+
+
+def _refresh_family_lock_key(family_id: UUID) -> int:
+    digest = blake2b(
+        family_id.bytes,
+        digest_size=8,
+        person=_REFRESH_FAMILY_LOCK_PERSON,
+    ).digest()
+    return int.from_bytes(digest, byteorder="big", signed=True)
+
+
+def _session_is_active(row: RefreshSessionRow, now: datetime) -> bool:
+    return (
+        row.revoked_at is None
+        and row.replaced_by_session_id is None
+        and now - row.last_used_at < REFRESH_INACTIVITY_LIFETIME
+        and now - row.family_created_at < REFRESH_ABSOLUTE_LIFETIME
+    )
+
+
+def _user_value(row: UserRow) -> IdentityUser:
+    return IdentityUser(
+        user_id=row.user_id,
+        username=row.username,
+        normalized_username=row.normalized_username,
+        password_hash=row.password_hash,
+        is_active=row.is_active,
+        failed_access_count=row.failed_access_count,
+        lockout_end=row.lockout_end,
+        permission_version=row.permission_version,
+    )
+
+
+def _role_value(row: RoleRow) -> IdentityRole:
+    return IdentityRole(
+        role_id=row.role_id,
+        name=row.name,
+        normalized_name=row.normalized_name,
+        permission_version=row.permission_version,
+    )
+
+
+def _refresh_row(value: RefreshSession) -> RefreshSessionRow:
+    return RefreshSessionRow(
+        session_id=value.session_id,
+        user_id=value.user_id,
+        family_id=value.family_id,
+        token_hash=value.token_hash,
+        created_at=value.created_at,
+        family_created_at=value.family_created_at,
+        last_used_at=value.last_used_at,
+        revoked_at=value.revoked_at,
+        replaced_by_session_id=value.replaced_by_session_id,
+    )

python_platform/identity/tokens.py

@@ -0,0 +1,106 @@
+"""固定 HS256、完整 required claims 与 Host-owned keyring 的 JWT boundary。"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from uuid import UUID, uuid4
+
+import jwt
+
+from ..options import Options
+from .contracts import IdentityOptions
+from .errors import InvalidCredentialsError
+
+ACCESS_TOKEN_LIFETIME = timedelta(minutes=15)
+REFRESH_INACTIVITY_LIFETIME = timedelta(days=30)
+REFRESH_ABSOLUTE_LIFETIME = timedelta(days=90)
+ACCESS_TOKEN_TYPE = "access"
+BEARER_TOKEN_TYPE = "Bearer"
+
+
+@dataclass(frozen=True, slots=True)
+class AccessTokenClaims:
+    user_id: UUID
+    session_id: UUID
+
+
+class JwtTokenService:
+    __slots__ = ("_options",)
+
+    def __init__(self, options: Options[IdentityOptions]) -> None:
+        self._options = options.value
+
+    def issue(self, user_id: UUID, session_id: UUID, *, now: datetime) -> str:
+        issued = _as_utc(now)
+        payload = {
+            "iss": self._options.issuer,
+            "aud": self._options.audience,
+            "sub": str(user_id),
+            "sid": str(session_id),
+            "jti": str(uuid4()),
+            "iat": issued,
+            "nbf": issued,
+            "exp": issued + ACCESS_TOKEN_LIFETIME,
+            "typ": ACCESS_TOKEN_TYPE,
+        }
+        key = self._options.keys[self._options.active_kid].get_secret_value()
+        return jwt.encode(
+            payload,
+            key,
+            algorithm="HS256",
+            headers={"kid": self._options.active_kid, "typ": "JWT"},
+        )
+
+    def verify(self, token: str) -> AccessTokenClaims:
+        try:
+            header = jwt.get_unverified_header(token)
+            if header.get("alg") != "HS256":
+                raise InvalidCredentialsError
+            kid = header.get("kid")
+            if not isinstance(kid, str) or kid not in self._options.keys:
+                raise InvalidCredentialsError
+            payload = jwt.decode(
+                token,
+                self._options.keys[kid].get_secret_value(),
+                algorithms=["HS256"],
+                issuer=self._options.issuer,
+                audience=self._options.audience,
+                options={
+                    "require": ["iss", "aud", "sub", "sid", "jti", "iat", "nbf", "exp", "typ"]
+                },
+            )
+            if payload.get("typ") != ACCESS_TOKEN_TYPE:
+                raise InvalidCredentialsError
+            user_id = UUID(_required_string_claim(payload, "sub"))
+            session_id = UUID(_required_string_claim(payload, "sid"))
+            UUID(_required_string_claim(payload, "jti"))
+        except InvalidCredentialsError:
+            raise
+        except Exception:
+            raise InvalidCredentialsError from None
+        return AccessTokenClaims(user_id=user_id, session_id=session_id)
+
+
+def new_refresh_token() -> str:
+    # token_urlsafe(32) 以 32 random bytes 提供 256-bit entropy。
+    return secrets.token_urlsafe(32)
+
+
+def hash_refresh_token(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def _required_string_claim(payload: dict[str, object], name: str) -> str:
+    value = payload.get(name)
+    if not isinstance(value, str) or not value:
+        raise InvalidCredentialsError
+    return value
+
+
+def _as_utc(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        raise ValueError("security timestamps must be timezone-aware")
+    return value.astimezone(UTC)

python_platform/invocation/__init__.py

@@ -0,0 +1,3 @@
+from .contracts import ApplicationInvocationContext, BackgroundSystemCaller
+
+__all__ = ("ApplicationInvocationContext", "BackgroundSystemCaller")