terp-cap-groups 0.1.0__tar.gz

terp_cap_groups-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_groups-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: terp-cap-groups
+Version: 0.1.0
+Summary: Terp groups capability — admin-managed user groups that bundle access-grant permissions.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-cap-access==0.1.0
+Requires-Dist: terp-cap-identity==0.1.0
+Requires-Dist: terp-core==0.1.0

terp_cap_groups-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-groups"
+version = "0.1.0"
+description = "Terp groups capability — admin-managed user groups that bundle access-grant permissions."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    "terp-cap-access==0.1.0",
+    "terp-cap-identity==0.1.0",
+]
+
+# Self-registering: the kernel discovers this ModuleSpec via the entry point,
+# mounting the admin `groups` management router at /api/v1/groups without any
+# composition-root edit. Importing the package also registers the access
+# subject expander, so permissions granted to a group apply to its members.
+[project.entry-points."terp.capabilities"]
+groups = "terp.capabilities.groups:module"
+
+# Owns the `user_group` / `user_group_member` tables, so it ships an independent,
+# linear Alembic history (its own `alembic_version_groups` table), discovered by
+# `terp migrate` via the `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+groups = "terp.capabilities.groups"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.groups`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/groups"]

terp_cap_groups-0.1.0/src/terp/capabilities/groups/__init__.py

@@ -0,0 +1,55 @@
+"""terp.capabilities.groups — admin-managed user groups that bundle permissions.
+
+The kernel ``Policy`` guard enforces the coarse role ladder; the access
+capability adds per-permission grants. This capability adds the missing
+middle: **groups** — named sets of users that hold grants *collectively*:
+
+* persisted :class:`Group` / :class:`GroupMember` tables (flat, no nesting),
+* an audited :class:`GroupsService` (CRUD + idempotent membership management;
+  deleting a group cascades to its memberships and its grants atomically),
+* a **self-registering**, admin-only ``groups`` router at ``/api/v1/groups``,
+* the access subject-expansion bridge: importing this package registers
+  :func:`~terp.capabilities.groups.expander.expand_group_memberships`, so a
+  grant whose subject is a group id is effective for every member — through
+  ``require_permission`` and the kernel guard alike, with no call-site changes.
+
+Granting to a group is an ordinary access grant (``subject_id`` = the group's
+id). Groups carry permissions, never roles: the single-role ladder (ADR 0004)
+is untouched.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.groups.expander import (
+    expand_group_memberships,
+    register_group_expansion,
+)
+from terp.capabilities.groups.models import Group, GroupMember
+from terp.capabilities.groups.router import module, router
+from terp.capabilities.groups.schemas import (
+    GroupCreate,
+    GroupMemberAdd,
+    GroupMemberRead,
+    GroupRead,
+    GroupUpdate,
+)
+from terp.capabilities.groups.service import GroupsService
+
+# Importing the capability (entry-point discovery does) activates group-aware
+# permission checks; without the import, access behaves exactly as before.
+register_group_expansion()
+
+__all__ = [
+    "Group",
+    "GroupCreate",
+    "GroupMember",
+    "GroupMemberAdd",
+    "GroupMemberRead",
+    "GroupRead",
+    "GroupUpdate",
+    "GroupsService",
+    "expand_group_memberships",
+    "module",
+    "register_group_expansion",
+    "router",
+]

terp_cap_groups-0.1.0/src/terp/capabilities/groups/expander.py

@@ -0,0 +1,40 @@
+"""The groups → access bridge: expand a user to the groups they belong to.
+
+Registered into the access capability's subject-expansion seam at package import
+(entry-point discovery imports this package to mount the router, so installing
+the capability activates group-aware permission checks with no composition-root
+edit). From then on ``AccessService.has_permission`` — behind both
+``require_permission`` and the kernel guard's ``permission_enforcer`` — checks
+grants against the caller *and* the caller's groups.
+
+Membership lookup is one indexed query per check; expansion is flat by design
+(groups do not nest — a group id expands to nothing).
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterable
+
+from sqlmodel import Session
+
+from terp.capabilities.access import register_subject_expander
+
+from terp.capabilities.groups.service import GroupsService
+
+_service = GroupsService()
+
+
+def expand_group_memberships(
+    session: Session, subject_id: uuid.UUID
+) -> Iterable[uuid.UUID]:
+    """The ids of every group *subject_id* belongs to (empty for a non-member)."""
+    return _service.group_ids_for(session, subject_id)
+
+
+def register_group_expansion() -> None:
+    """Register the membership expander with the access capability (idempotent)."""
+    register_subject_expander(expand_group_memberships)
+
+
+__all__ = ["expand_group_memberships", "register_group_expansion"]

terp_cap_groups-0.1.0/src/terp/capabilities/groups/migrations/versions/bea53bcf1ad4_create_groups_tables.py

@@ -0,0 +1,67 @@
+"""create groups tables
+
+Revision ID: bea53bcf1ad4
+Revises: 
+Create Date: 2026-07-06 14:35:32.454331
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'bea53bcf1ad4'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('user_group',
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('version', sa.Integer(), nullable=False),
+    sa.Column('name', sqlmodel.sql.sqltypes.AutoString(length=200), nullable=False),
+    sa.Column('description', sqlmodel.sql.sqltypes.AutoString(length=500), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_user_group'))
+    )
+    with op.batch_alter_table('user_group', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_user_group_name'), ['name'], unique=True)
+
+    op.create_table('user_group_member',
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('version', sa.Integer(), nullable=False),
+    sa.Column('group_id', sa.Uuid(), nullable=False),
+    sa.Column('user_id', sa.Uuid(), nullable=False),
+    sa.ForeignKeyConstraint(['group_id'], ['user_group.id'], name=op.f('fk_user_group_member_group_id_user_group')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_user_group_member')),
+    sa.UniqueConstraint('group_id', 'user_id', name='uq_user_group_member_group_user')
+    )
+    with op.batch_alter_table('user_group_member', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_user_group_member_group_id'), ['group_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_user_group_member_user_id'), ['user_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('user_group_member', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_user_group_member_user_id'))
+        batch_op.drop_index(batch_op.f('ix_user_group_member_group_id'))
+
+    op.drop_table('user_group_member')
+    with op.batch_alter_table('user_group', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_user_group_name'))
+
+    op.drop_table('user_group')
+    # ### end Alembic commands ###

terp_cap_groups-0.1.0/src/terp/capabilities/groups/models.py

@@ -0,0 +1,43 @@
+"""The persisted group tables — admin-managed sets of users that bundle permissions.
+
+A :class:`Group` is a named collection; a :class:`GroupMember` is a single,
+immutable fact: *user ``user_id`` belongs to group ``group_id``*. Groups carry
+**permissions, not roles**: granting a permission to a group is an ordinary
+access grant whose ``subject_id`` is the group's id (the FK-less ``Grant``
+column anticipates exactly this), and the access capability's subject-expansion
+seam makes it effective for every member. The kernel role ladder is untouched —
+a group never changes anyone's rank.
+
+``user_id`` is an FK-less UUID for the same reason ``Grant.subject_id`` is: this
+capability must not import the higher-layer user table it references, so it stays
+a leaf. ``group_id`` *is* a real foreign key — both tables live in this package.
+
+The table names are ``user_group`` / ``user_group_member`` (never bare
+``group``, a reserved SQL keyword).
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field
+
+from terp.core import BaseTable
+
+
+class Group(BaseTable, table=True):
+    __tablename__ = "user_group"
+
+    name: str = Field(max_length=200, unique=True, index=True)
+    description: str = Field(default="", max_length=500)
+
+
+class GroupMember(BaseTable, table=True):
+    __tablename__ = "user_group_member"
+    __table_args__ = (
+        UniqueConstraint("group_id", "user_id", name="uq_user_group_member_group_user"),
+    )
+
+    group_id: uuid.UUID = Field(foreign_key="user_group.id", index=True)
+    user_id: uuid.UUID = Field(index=True)

terp_cap_groups-0.1.0/src/terp/capabilities/groups/router.py

@@ -0,0 +1,123 @@
+"""Admin ``groups`` router + the discoverable ``ModuleSpec``.
+
+**Admin-only** (``Policy`` requires ``ADMIN``): managing who belongs to which
+permission-bundling group is itself a privileged action, exactly like managing
+grants. Exposed as ``module`` so the kernel's entry-point discovery mounts it at
+``/api/v1/groups`` with no composition-root edit.
+
+Granting a permission *to a group* is not done here — it is an ordinary access
+grant (``POST /api/v1/access/grants``) whose ``subject_id`` is the group's id;
+this router manages the groups and their memberships.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter
+
+from terp.core import ModuleSpec, Page, PaginationDep, Policy, Roles, SessionDep
+
+from terp.capabilities.groups.models import Group
+from terp.capabilities.groups.schemas import (
+    GroupCreate,
+    GroupMemberAdd,
+    GroupMemberRead,
+    GroupRead,
+    GroupUpdate,
+)
+from terp.capabilities.groups.service import GroupsService
+
+router = APIRouter(tags=["groups"])
+_service = GroupsService()
+
+
+def _read(group: Group, member_count: int) -> GroupRead:
+    return GroupRead(
+        id=group.id,
+        name=group.name,
+        description=group.description,
+        member_count=member_count,
+        version=group.version,
+        created_at=group.created_at,
+        updated_at=group.updated_at,
+    )
+
+
+@router.get("/", response_model=Page[GroupRead])
+def list_groups(session: SessionDep, pagination: PaginationDep) -> Page[GroupRead]:
+    rows, total = _service.list(session, skip=pagination.skip, limit=pagination.limit)
+    counts = _service.member_counts(session, [row.id for row in rows])
+    return Page[GroupRead].of(
+        [_read(row, counts.get(row.id, 0)) for row in rows], total, pagination
+    )
+
+
+@router.post("/", response_model=GroupRead, status_code=201)
+def create_group(payload: GroupCreate, session: SessionDep) -> GroupRead:
+    return _read(_service.create(session, payload), 0)
+
+
+@router.get("/{group_id}", response_model=GroupRead)
+def get_group(group_id: uuid.UUID, session: SessionDep) -> GroupRead:
+    group = _service.get(session, group_id)
+    counts = _service.member_counts(session, [group.id])
+    return _read(group, counts.get(group.id, 0))
+
+
+@router.patch("/{group_id}", response_model=GroupRead)
+def update_group(
+    group_id: uuid.UUID, payload: GroupUpdate, session: SessionDep
+) -> GroupRead:
+    group = _service.update(session, group_id, payload)
+    counts = _service.member_counts(session, [group.id])
+    return _read(group, counts.get(group.id, 0))
+
+
+@router.delete("/{group_id}", status_code=204)
+def delete_group(group_id: uuid.UUID, session: SessionDep) -> None:
+    _service.delete(session, group_id)
+
+
+@router.get("/{group_id}/members", response_model=Page[GroupMemberRead])
+def list_members(
+    group_id: uuid.UUID, session: SessionDep, pagination: PaginationDep
+) -> Page[GroupMemberRead]:
+    rows, total = _service.members_for(
+        session, group_id, skip=pagination.skip, limit=pagination.limit
+    )
+    emails = _service.member_emails(session, [row.user_id for row in rows])
+    items = [
+        GroupMemberRead(
+            id=row.id,
+            group_id=row.group_id,
+            user_id=row.user_id,
+            email=emails.get(row.user_id),
+            created_at=row.created_at,
+        )
+        for row in rows
+    ]
+    return Page[GroupMemberRead].of(items, total, pagination)
+
+
+@router.post("/{group_id}/members", response_model=GroupMemberRead, status_code=201)
+def add_member(
+    group_id: uuid.UUID, payload: GroupMemberAdd, session: SessionDep
+) -> GroupMemberRead:
+    return GroupMemberRead.model_validate(
+        _service.add_member(session, group_id, payload.user_id)
+    )
+
+
+@router.delete("/{group_id}/members/{user_id}", status_code=204)
+def remove_member(
+    group_id: uuid.UUID, user_id: uuid.UUID, session: SessionDep
+) -> None:
+    _service.remove_member(session, group_id, user_id)
+
+
+module = ModuleSpec(
+    name="groups",
+    router=router,
+    policy=Policy(read_role=Roles.ADMIN, write_role=Roles.ADMIN),
+)

terp_cap_groups-0.1.0/src/terp/capabilities/groups/schemas.py

@@ -0,0 +1,49 @@
+"""Group DTOs — the admin surface's request / response shapes.
+
+``GroupRead`` carries a live ``member_count`` so the admin overview can show
+group sizes without N+1 member listings. Memberships are immutable rows
+(add / remove, never edited), so there is no member ``*Update`` surface.
+"""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+
+from sqlmodel import Field
+
+from terp.core import BaseSchema, BaseUpdateSchema
+
+
+class GroupCreate(BaseSchema):
+    name: str = Field(max_length=200)
+    description: str = Field(default="", max_length=500)
+
+
+class GroupUpdate(BaseUpdateSchema):
+    name: str | None = Field(default=None, max_length=200)
+    description: str | None = Field(default=None, max_length=500)
+
+
+class GroupRead(BaseSchema):
+    id: uuid.UUID
+    name: str
+    description: str
+    member_count: int
+    version: int
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+
+
+class GroupMemberAdd(BaseSchema):
+    user_id: uuid.UUID
+
+
+class GroupMemberRead(BaseSchema):
+    id: uuid.UUID
+    group_id: uuid.UUID
+    user_id: uuid.UUID
+    # Resolved from the identity store when the member listing is served (one query
+    # per page); None when the account no longer exists (user_id is FK-less).
+    email: str | None = None
+    created_at: datetime.datetime

terp_cap_groups-0.1.0/src/terp/capabilities/groups/service.py

@@ -0,0 +1,174 @@
+"""Groups service — audited group CRUD + membership management.
+
+Everything rides the kernel ``BaseService`` chokepoints, so every mutation is
+audited and atomic: memberships are managed through a private member service
+(``_save`` / ``_remove``), and deleting a group cascades — inside the *same*
+write unit (ADR 0038) — to its membership rows and to the access grants naming
+the group as subject, so no orphan grant keeps authorizing former members.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlmodel import Session, col, func, select
+
+from terp.core import AuditAction, BaseService, BaseUpdateSchema, NotFoundError
+
+from terp.capabilities.access import AccessService
+from terp.capabilities.identity import User
+
+from terp.capabilities.groups.models import Group, GroupMember
+from terp.capabilities.groups.schemas import GroupCreate, GroupMemberAdd, GroupUpdate
+
+
+class _GroupMemberUpdate(BaseUpdateSchema):
+    """Memberships are immutable (group + user) — nothing is updatable.
+
+    Present only to satisfy ``BaseService``'s ``UpdateT`` type parameter; the
+    router never exposes a member update route.
+    """
+
+
+class _MembersService(BaseService[GroupMember, GroupMemberAdd, _GroupMemberUpdate]):
+    """Internal audited chokepoint for membership rows (not part of the public API)."""
+
+    model = GroupMember
+
+
+class GroupsService(BaseService[Group, GroupCreate, GroupUpdate]):
+    model = Group
+
+    def __init__(self) -> None:
+        self._members = _MembersService()
+
+    # -- membership -------------------------------------------------------------
+
+    def _find_member(
+        self, session: Session, group_id: uuid.UUID, user_id: uuid.UUID
+    ) -> GroupMember | None:
+        return session.exec(
+            self._members.base_query().where(
+                GroupMember.group_id == group_id, GroupMember.user_id == user_id
+            )
+        ).first()
+
+    def add_member(
+        self, session: Session, group_id: uuid.UUID, user_id: uuid.UUID
+    ) -> GroupMember:
+        """Add *user_id* to the group (idempotent: re-adding returns the existing row)."""
+        self.get(session, group_id)  # 404 before any write when the group is gone
+        existing = self._find_member(session, group_id, user_id)
+        if existing is not None:
+            return existing
+        # Membership changes effective permissions — an audit-sensitive change, so
+        # it routes through the audited chokepoint like a grant does.
+        entity = GroupMember(group_id=group_id, user_id=user_id)
+        return self._members._save(session, entity, AuditAction.CREATED)
+
+    def remove_member(
+        self, session: Session, group_id: uuid.UUID, user_id: uuid.UUID
+    ) -> None:
+        """Remove *user_id* from the group; unknown group or non-member is a 404."""
+        self.get(session, group_id)
+        existing = self._find_member(session, group_id, user_id)
+        if existing is None:
+            raise NotFoundError()
+        self._members._remove(session, existing)
+
+    def members_for(
+        self, session: Session, group_id: uuid.UUID, *, skip: int, limit: int
+    ) -> tuple[list[GroupMember], int]:
+        """Paginated membership rows of one group (admin listing)."""
+        self.get(session, group_id)
+        return self._members._paginate(
+            session,
+            self._members.base_query().where(GroupMember.group_id == group_id),
+            skip=skip,
+            limit=limit,
+        )
+
+    def group_ids_for(self, session: Session, user_id: uuid.UUID) -> set[uuid.UUID]:
+        """The ids of every group *user_id* belongs to (the subject-expansion source)."""
+        rows = session.exec(
+            select(GroupMember.group_id).where(GroupMember.user_id == user_id)
+        ).all()
+        return set(rows)
+
+    def member_emails(
+        self, session: Session, user_ids: list[uuid.UUID]
+    ) -> dict[uuid.UUID, str]:
+        """Resolve member user ids to emails in one query (page-sized input).
+
+        Backs the member listing's ``email`` enrichment: the UI shows accounts,
+        not UUIDs, without holding a client-side directory. A vanished account
+        (``user_id`` is FK-less) is simply absent from the map.
+        """
+        if not user_ids:
+            return {}
+        rows = session.exec(
+            select(User.id, User.email).where(col(User.id).in_(user_ids))
+        ).all()
+        return dict(rows)
+
+    # -- read helpers ------------------------------------------------------------
+
+    def member_counts(
+        self, session: Session, group_ids: list[uuid.UUID]
+    ) -> dict[uuid.UUID, int]:
+        """Member totals for *group_ids* in one grouped query (no N+1 in listings)."""
+        if not group_ids:
+            return {}
+        rows = session.exec(
+            select(GroupMember.group_id, func.count())
+            .where(col(GroupMember.group_id).in_(group_ids))
+            .group_by(GroupMember.group_id)
+        ).all()
+        return dict(rows)
+
+    # -- cascade -----------------------------------------------------------------
+
+    def _after_write(self, session: Session, entity: Group, action: AuditAction) -> None:
+        """Deleting a group cascades to its memberships and its grants, atomically.
+
+        Runs inside the same write unit as the group's own ``DELETED`` record
+        (ADR 0038): the nested audited removals join the transaction and flush
+        before the group row is deleted, so the FK holds and a failure anywhere
+        rolls back the whole cascade. Grants naming the group as subject are
+        revoked through the access service, so a deleted group cannot keep
+        authorizing its former members via a dangling subject id.
+        """
+        super()._after_write(session, entity, action)
+        if action is not AuditAction.DELETED:
+            return
+        # Drain in batches until nothing remains: nested audited removals flush into
+        # this same transaction, so each pass sees the prior pass's deletes. No size
+        # cliff — a group of any size cascades completely or rolls back completely.
+        while True:
+            members, _total = self._members._paginate(
+                session,
+                self._members.base_query().where(GroupMember.group_id == entity.id),
+                skip=0,
+                limit=_CASCADE_BATCH,
+            )
+            if not members:
+                break
+            for member in members:
+                self._members._remove(session, member)
+        access = AccessService()
+        while True:
+            grants, _grant_total = access.list_for(
+                session, entity.id, skip=0, limit=_CASCADE_BATCH
+            )
+            if not grants:
+                break
+            for grant in grants:
+                access.delete(session, grant.id)
+
+
+# Rows fetched per cascade pass (the loop above drains every pass until empty,
+# so this bounds memory per pass — never the cascade's total size).
+_CASCADE_BATCH = 1_000
+
+
+__all__ = ["GroupsService"]