terp-cap-users 0.1.0__tar.gz

terp_cap_users-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_users-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: terp-cap-users
+Version: 0.1.0
+Summary: Terp users capability — admin user management over the identity store.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-cap-auth==0.1.0
+Requires-Dist: terp-cap-identity==0.1.0
+Requires-Dist: terp-core==0.1.0

terp_cap_users-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-users"
+version = "0.1.0"
+description = "Terp users capability — admin user management over the identity store."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    "terp-cap-identity==0.1.0",
+    "terp-cap-auth==0.1.0",
+]
+
+# Self-registering: the kernel discovers this ModuleSpec via the entry point,
+# mounting the admin `users` management router at /api/v1/users without any edit
+# to a composition root. It owns the user-administration surface over the
+# identity store (which keeps the User model + authenticate).
+[project.entry-points."terp.capabilities"]
+users = "terp.capabilities.users:module"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.users`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/users"]

terp_cap_users-0.1.0/src/terp/capabilities/users/__init__.py

@@ -0,0 +1,33 @@
+"""terp.capabilities.users — admin user management over the identity store.
+
+Provides a :class:`UsersService` and a **self-registering** admin ``users`` router
+(list / get / provision / edit / deactivate / reactivate / reset password). The
+kernel discovers ``module`` via the ``terp.capabilities`` entry point and mounts
+it at ``/api/v1/users`` with no composition-root edit.
+
+The persisted ``User`` (and ``authenticate``) live in ``terp-cap-identity``; this
+capability is the **administration surface** over that store, so there is a single
+user table shared with the login path. Every write is audited (it routes through
+the ``BaseService`` chokepoint) and passwords are hashed via ``terp-cap-auth``.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.users.router import module, router
+from terp.capabilities.users.schemas import (
+    UserAdminUpdate,
+    UserPasswordReset,
+    UserProvision,
+    UserRead,
+)
+from terp.capabilities.users.service import UsersService
+
+__all__ = [
+    "UserAdminUpdate",
+    "UserPasswordReset",
+    "UserProvision",
+    "UserRead",
+    "UsersService",
+    "module",
+    "router",
+]

terp_cap_users-0.1.0/src/terp/capabilities/users/router.py

@@ -0,0 +1,128 @@
+"""Admin user-management router + the discoverable ``ModuleSpec``.
+
+Admin-only (``Policy`` requires ``ADMIN`` for both read and write). Mounted at
+``/api/v1/users`` purely via entry-point discovery — it owns the
+user-administration surface over the identity store: list / get / provision /
+edit / deactivate / reactivate / reset password. Deactivation is preferred over
+deletion, so a user is never hard-removed here.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, Query
+
+from terp.core import (
+    ModuleSpec,
+    Page,
+    PaginationDep,
+    Policy,
+    Principal,
+    Roles,
+    SessionDep,
+    get_principal,
+)
+
+from terp.capabilities.identity import RefreshTokenService
+from terp.capabilities.users.schemas import (
+    UserAdminUpdate,
+    UserPasswordReset,
+    UserProvision,
+    UserRead,
+)
+from terp.capabilities.users.service import UsersService
+
+router = APIRouter(tags=["users"])
+# Admin security actions (deactivate / demote / reset-password) also revoke the target's
+# refresh-token families (ADR 0054), so a reset after a compromise kills the refresh cookie
+# too — not just the short-lived access token. For an app that issues no refresh tokens this
+# is a harmless no-op (the family query returns nothing).
+_service = UsersService(refresh_revoker=RefreshTokenService().revoke_all_for_user)
+
+
+@router.get("/", response_model=Page[UserRead])
+def list_users(
+    session: SessionDep,
+    pagination: PaginationDep,
+    email: str | None = Query(
+        None,
+        max_length=254,
+        description="Filter to users whose email contains this text (case-insensitive).",
+    ),
+) -> Page[UserRead]:
+    if email:
+        rows, total = _service.list_matching(
+            session, email=email, skip=pagination.skip, limit=pagination.limit
+        )
+    else:
+        rows, total = _service.list(
+            session, skip=pagination.skip, limit=pagination.limit
+        )
+    return Page[UserRead].of(
+        [UserRead.model_validate(row) for row in rows], total, pagination
+    )
+
+
+@router.post("/", response_model=UserRead, status_code=201)
+def provision_user(payload: UserProvision, session: SessionDep) -> UserRead:
+    return UserRead.model_validate(_service.create(session, payload))
+
+
+@router.get("/{user_id}", response_model=UserRead)
+def get_user(user_id: uuid.UUID, session: SessionDep) -> UserRead:
+    return UserRead.model_validate(_service.get(session, user_id))
+
+
+@router.patch("/{user_id}", response_model=UserRead)
+def update_user(
+    user_id: uuid.UUID,
+    payload: UserAdminUpdate,
+    session: SessionDep,
+    principal: Principal | None = Depends(get_principal),
+) -> UserRead:
+    return UserRead.model_validate(
+        _service.update(
+            session,
+            user_id,
+            payload,
+            actor_id=principal.id if principal is not None else None,
+        )
+    )
+
+
+@router.post("/{user_id}/deactivate", response_model=UserRead)
+def deactivate_user(
+    user_id: uuid.UUID,
+    session: SessionDep,
+    principal: Principal | None = Depends(get_principal),
+) -> UserRead:
+    return UserRead.model_validate(
+        _service.set_active(
+            session,
+            user_id,
+            active=False,
+            actor_id=principal.id if principal is not None else None,
+        )
+    )
+
+
+@router.post("/{user_id}/reactivate", response_model=UserRead)
+def reactivate_user(user_id: uuid.UUID, session: SessionDep) -> UserRead:
+    return UserRead.model_validate(_service.set_active(session, user_id, active=True))
+
+
+@router.post("/{user_id}/reset-password", response_model=UserRead)
+def reset_user_password(
+    user_id: uuid.UUID, payload: UserPasswordReset, session: SessionDep
+) -> UserRead:
+    return UserRead.model_validate(
+        _service.reset_password(session, user_id, payload.password)
+    )
+
+
+module = ModuleSpec(
+    name="users",
+    router=router,
+    policy=Policy(read_role=Roles.ADMIN, write_role=Roles.ADMIN),
+)

terp_cap_users-0.1.0/src/terp/capabilities/users/schemas.py

@@ -0,0 +1,56 @@
+"""Users capability DTOs — admin management over the identity ``User`` store.
+
+The read shape reuses identity's ``UserRead`` (which never exposes
+``hashed_password``); this module adds the admin write DTOs. ``UserAdminUpdate``
+requires the optimistic-concurrency ``version`` like every other update schema.
+
+The ``password`` ``max_length`` is the DoS cap; *strength* is enforced one layer in,
+at the ``UsersService`` write chokepoint (ADR 0032), so a rejection is the uniform
+typed ``WeakPasswordError`` envelope rather than a raw pydantic 422.
+"""
+
+from __future__ import annotations
+
+from sqlmodel import Field
+
+from terp.core import BaseSchema, BaseUpdateSchema, Roles
+
+from terp.capabilities.identity import UserRead
+
+__all__ = [
+    "UserAdminUpdate",
+    "UserPasswordReset",
+    "UserProvision",
+    "UserRead",
+]
+
+
+class UserProvision(BaseSchema):
+    """Admin-provisions a new user with an initial password and a role *rank*.
+
+    ``role`` is an integer rank resolved against the app's ``PermissionModel`` at
+    login (ADR 0022), so an admin can provision any role the app's ladder defines —
+    not only the default three tiers; an unmodeled rank simply fails closed at that
+    user's next login. The default is the viewer rank.
+    """
+
+    email: str = Field(max_length=320)
+    password: str = Field(max_length=256)
+    role: int = Field(default=int(Roles.VIEWER), ge=0)
+
+
+class UserAdminUpdate(BaseUpdateSchema):
+    """Admin edits a user's email / role rank (OCC ``version`` required).
+
+    Activation state is changed through the dedicated ``deactivate`` /
+    ``reactivate`` actions, not this generic patch.
+    """
+
+    email: str | None = Field(default=None, max_length=320)
+    role: int | None = Field(default=None, ge=0)
+
+
+class UserPasswordReset(BaseSchema):
+    """Admin sets a new password for a user."""
+
+    password: str = Field(max_length=256)

terp_cap_users-0.1.0/src/terp/capabilities/users/service.py

@@ -0,0 +1,242 @@
+"""Users service — admin management over the identity ``User`` store.
+
+Builds on identity's persisted ``User``: every write routes through the audited
+``BaseService`` chokepoint, so admin provisioning, role/email edits, deactivation,
+and password resets each land an audit record (and a soft-delete-style
+deactivation is preferred over a hard delete). Passwords are hashed via the auth
+capability. Reads (``list`` / ``get``) are inherited unchanged.
+
+A safety invariant guards the admin surface itself: an action that would leave the
+system with **no active administrator** — deactivating or demoting the last active
+admin — is refused (fail-closed), so an admin can never lock every administrator
+out of the admin-only routes.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from threading import RLock
+from typing import ClassVar
+
+from sqlmodel import Session, col, select
+
+from terp.capabilities.auth import hash_password
+from terp.core import AppError, AuditAction, BaseService, Roles, validate_password
+
+from terp.capabilities.identity import User
+from terp.capabilities.users.schemas import UserAdminUpdate, UserProvision
+
+_ADMIN_RANK = int(Roles.ADMIN)
+
+
+class LastAdminError(AppError):
+    """409 — the action would leave the system with no active administrator."""
+
+    status_code = 409
+    code = "last_admin_protected"
+    default_message = (
+        "This action would remove the last active administrator and is refused; "
+        "promote or activate another administrator first."
+    )
+
+
+class SelfAdminActionError(AppError):
+    """409 — an administrator may not deactivate or demote their own account."""
+
+    status_code = 409
+    code = "self_admin_action_protected"
+    default_message = (
+        "Administrators cannot deactivate or demote their own administrator account; "
+        "ask another active administrator to perform this action."
+    )
+
+
+class UsersService(BaseService[User, UserProvision, UserAdminUpdate]):
+    model = User
+    _admin_invariant_lock: ClassVar[RLock] = RLock()
+
+    def __init__(
+        self, refresh_revoker: Callable[[Session, uuid.UUID], None] | None = None
+    ) -> None:
+        """Optionally wire a *refresh_revoker* (ADR 0054).
+
+        When supplied, every audited user security update also revokes the user's
+        refresh-token families in ``_after_write``, so a logout / deactivate / demote /
+        password-reset kills *both* the access-token epoch and the refresh cookie in the
+        same transaction. Unwired (the default), revocation is ADR 0031's epoch-only
+        behaviour, unchanged.
+        """
+        self._refresh_revoker = refresh_revoker
+
+    def create(self, session: Session, data: UserProvision) -> User:
+        """Provision a new user (password hashed), audited via the write chokepoint.
+
+        The credential boundary enforces the app's ``PasswordPolicy`` (ADR 0032): a weak
+        password is refused with the uniform ``WeakPasswordError`` before it is hashed; the
+        DTO's ``max_length`` stays the separate DoS cap.
+        """
+        validate_password(data.password)
+        user = User(
+            email=data.email,
+            hashed_password=hash_password(data.password),
+            role=int(data.role),
+        )
+        return self._save(session, user, AuditAction.CREATED)
+
+    def get_by_email(self, session: Session, email: str) -> User | None:
+        """Find a user by email, or ``None`` — the lookup the bootstrap / seed paths share."""
+        return session.exec(select(User).where(User.email == email)).first()
+
+    def list_matching(
+        self, session: Session, *, email: str, skip: int, limit: int
+    ) -> tuple[list[User], int]:
+        """Paginated users whose email contains *email* (case-insensitive).
+
+        The directory-lookup primitive behind the admin surface's ``?email=``
+        filter: member pickers and admin searches resolve an account by typing
+        part of its address instead of paging through the whole directory.
+        Builds on ``base_query`` like every read.
+        """
+        return self._paginate(
+            session,
+            self.base_query().where(col(User.email).icontains(email)),
+            skip=skip,
+            limit=limit,
+        )
+
+    def ensure_user(self, session: Session, data: UserProvision) -> User:
+        """Idempotent provisioning: return the existing user for ``data.email``, else create one.
+
+        The create-if-absent primitive for bootstrap and seed paths (``terp user create`` /
+        ``terp seed``): the lookup + audited create live here once, so a caller never
+        re-implements the query. An already-present user is returned untouched (no password
+        reset, no role change), so re-running a seed is a safe no-op.
+        """
+        existing = self.get_by_email(session, data.email)
+        if existing is not None:
+            return existing
+        return self.create(session, data)
+
+    def update(
+        self,
+        session: Session,
+        entity_id: uuid.UUID,
+        data: UserAdminUpdate,
+        *,
+        actor_id: uuid.UUID | None = None,
+    ) -> User:
+        """Admin edit (email / role) with OCC — refusing to demote the last admin.
+
+        A role or email change is security-relevant (a demotion, or an email change that
+        re-tenants the user), so it bumps the token epoch in the **same** write — revoking
+        the user's outstanding tokens at once (ADR 0031) instead of leaving the old rank /
+        tenant live for the access-token lifetime.
+        """
+        with self._admin_invariant_lock:
+            user = self.get(session, entity_id)
+            if data.role is not None and int(data.role) < _ADMIN_RANK:
+                if actor_id is not None and user.id == actor_id:
+                    raise SelfAdminActionError()
+                if self._is_last_active_admin(session, user):
+                    raise LastAdminError()
+            # Do the OCC check before bumping the token epoch. Bumping first leaves a
+            # dirty object behind if the stale-version check raises; a later commit on the
+            # same session could otherwise revoke sessions even though the update failed.
+            if user.version != data.version:
+                from terp.core import StaleDataError
+
+                raise StaleDataError()
+            patch = self._without_managed_columns(data.model_dump(exclude_unset=True))
+            for key, value in patch.items():
+                setattr(user, key, value)
+            self._bump_token_version(user)
+            return self._save(session, user, AuditAction.UPDATED)
+
+    def set_active(
+        self,
+        session: Session,
+        user_id: uuid.UUID,
+        *,
+        active: bool,
+        actor_id: uuid.UUID | None = None,
+    ) -> User:
+        """Deactivate / reactivate a user (audited) — preferred over a hard delete.
+
+        Deactivating the last active administrator is refused, so the admin-only
+        surface can never be locked out for everyone. A deactivation also bumps the
+        token epoch, so the user's outstanding tokens stop working at once — defense in
+        depth atop the principal seam's mid-session ``is_active`` re-check (ADR 0031).
+        """
+        with self._admin_invariant_lock:
+            user = self.get(session, user_id)
+            if not active:
+                if actor_id is not None and user.id == actor_id:
+                    raise SelfAdminActionError()
+                if self._is_last_active_admin(session, user):
+                    raise LastAdminError()
+                self._bump_token_version(user)
+            user.is_active = active
+            return self._save(session, user, AuditAction.UPDATED)
+
+    def reset_password(
+        self, session: Session, user_id: uuid.UUID, new_password: str
+    ) -> User:
+        """Set a new password for a user (hashed, audited).
+
+        Resetting the password revokes the user's outstanding tokens (the epoch bump),
+        so a live session on the old credential cannot survive the reset (ADR 0031).
+        """
+        validate_password(new_password)
+        user = self.get(session, user_id)
+        user.hashed_password = hash_password(new_password)
+        self._bump_token_version(user)
+        return self._save(session, user, AuditAction.UPDATED)
+
+    def revoke_sessions(self, session: Session, user_id: uuid.UUID) -> None:
+        """Invalidate a user's outstanding tokens — the logout / forced-logout write.
+
+        Bumps the token epoch through the audited chokepoint, so every token minted
+        before this is rejected at its next request (ADR 0031). The auth capability's
+        ``/logout`` route wires this as its ``revoke_sessions`` seam (auth does not own
+        the store it must write).
+        """
+        user = self.get(session, user_id)
+        self._bump_token_version(user)
+        self._save(session, user, AuditAction.UPDATED)
+
+    def _after_write(self, session: Session, entity: User, action: AuditAction) -> None:
+        """Join refresh-token revocation to the audited user write (ADR 0054).
+
+        ``BaseService._save`` calls this after staging the ``identity_user`` update + audit
+        record and before the single outer commit. That makes the access-token epoch bump,
+        audit trail, and refresh-family revocation one atomic write unit; if any part raises,
+        none commits.
+        """
+        super()._after_write(session, entity, action)
+        if action is AuditAction.UPDATED and self._refresh_revoker is not None:
+            self._refresh_revoker(session, entity.id)
+
+    @staticmethod
+    def _bump_token_version(user: User) -> None:
+        """Advance the token epoch (ADR 0031); refresh families revoke in ``_after_write``.
+
+        The refresh-token revoker (when wired) runs from :meth:`_after_write`, inside the
+        same ``BaseService._save`` transaction as the audited user update.
+        """
+        user.token_version += 1
+
+    def _is_last_active_admin(self, session: Session, user: User) -> bool:
+        """True when *user* is an active admin and no other active admin remains."""
+        if not (user.is_active and user.role >= _ADMIN_RANK):
+            return False
+        return self._active_admin_count(session) <= 1
+
+    def _active_admin_count(self, session: Session) -> int:
+        """Count active admins, locking those rows where the database supports it."""
+        admins = session.exec(
+            select(User)
+            .where(User.is_active, User.role >= _ADMIN_RANK)  # type: ignore[arg-type]
+            .with_for_update()
+        ).all()
+        return len(admins)