terp-cap-access 0.1.0__tar.gz

terp_cap_access-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_access-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: terp-cap-access
+Version: 0.1.0
+Summary: Terp access capability — RBAC permission grants + a fail-closed require_permission dependency.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-core==0.1.0

terp_cap_access-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-access"
+version = "0.1.0"
+description = "Terp access capability — RBAC permission grants + a fail-closed require_permission dependency."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+]
+
+# Self-registering: the kernel discovers this ModuleSpec via the entry point,
+# mounting the admin `access` (grants) router without any composition-root edit.
+[project.entry-points."terp.capabilities"]
+access = "terp.capabilities.access:module"
+
+# Owns the `access_grant` table, so it ships an independent, linear Alembic history
+# (its own `alembic_version_access` table), discovered by `terp migrate` via the
+# `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+access = "terp.capabilities.access"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.access`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/access"]

terp_cap_access-0.1.0/src/terp/capabilities/access/__init__.py

@@ -0,0 +1,45 @@
+"""terp.capabilities.access — RBAC permission grants + ``require_permission``.
+
+The fourth opt-in capability and the remaining base-profile authorization piece.
+The kernel ``Policy`` guard enforces the coarse, global role ladder; this
+capability adds **fine-grained, per-permission** authorization on top:
+
+* a persisted :class:`Grant` (subject ↦ open, app-defined permission token),
+* an :class:`AccessService` (idempotent ``grant`` / ``revoke`` / ``has_permission``),
+* a fail-closed :func:`require_permission` dependency modules mount on a route,
+* a **self-registering**, admin-only ``access`` router to administer grants.
+
+It depends only on ``terp-core``: it reads the caller through the kernel's public
+``get_principal`` seam (which ``create_app`` points at the configured provider),
+so it never imports the auth capability.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.access.deps import enforce_permission, require_permission
+from terp.capabilities.access.expansion import (
+    SubjectExpander,
+    register_subject_expander,
+    reset_subject_expanders,
+    subject_ids_for,
+)
+from terp.capabilities.access.models import Grant
+from terp.capabilities.access.router import module, router
+from terp.capabilities.access.schemas import GrantCreate, GrantRead, GrantUpdate
+from terp.capabilities.access.service import AccessService
+
+__all__ = [
+    "AccessService",
+    "Grant",
+    "GrantCreate",
+    "GrantRead",
+    "GrantUpdate",
+    "SubjectExpander",
+    "enforce_permission",
+    "module",
+    "register_subject_expander",
+    "require_permission",
+    "reset_subject_expanders",
+    "router",
+    "subject_ids_for",
+]

terp_cap_access-0.1.0/src/terp/capabilities/access/deps.py

@@ -0,0 +1,78 @@
+"""``require_permission`` — a fail-closed, fine-grained authorization dependency.
+
+The module-level ``Policy`` guard enforces the coarse role ladder; this dependency
+enforces an **open, app-defined permission** on a single route or router, on top
+of (or instead of) a role. It is the runtime half of access's two-layer control:
+deny-by-default — an unauthenticated caller gets 401, an authenticated caller
+without the grant gets 403::
+
+    from terp.capabilities.access import require_permission
+
+    @router.post("/export", dependencies=[Depends(require_permission("reports:export"))])
+    def export(...): ...
+
+It reads the caller through the kernel's public ``get_principal`` seam, which
+``create_app`` points at the configured provider (e.g. the auth capability), so
+this capability never imports auth.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+
+from fastapi import Depends
+from sqlmodel import Session
+
+from terp.core import (
+    AuthenticationError,
+    PermissionDeniedError,
+    Permission,
+    Principal,
+    SessionDep,
+    get_principal,
+)
+
+from terp.capabilities.access.service import AccessService
+
+_service = AccessService()
+
+
+def require_permission(permission: str | Permission) -> Callable[..., None]:
+    """Build a dependency requiring *permission* (deny-by-default).
+
+    ``Permission`` is the Phase-A typed path. ``str`` remains for compatibility
+    until the architecture rule can guide modules to the control plane.
+    """
+
+    permission_name = permission.name if isinstance(permission, Permission) else permission
+
+    def dependency(
+        session: SessionDep,
+        principal: Principal | None = Depends(get_principal),
+    ) -> None:
+        if principal is None:
+            raise AuthenticationError()
+        if not _service.has_permission(session, principal.id, permission_name):
+            raise PermissionDeniedError()
+
+    # Introspection marker (never a control): `terp inspect access` reads this to
+    # surface route-level permission requirements in the access graph.
+    dependency.__terp_required_permission__ = permission_name  # type: ignore[attr-defined]
+    return dependency
+
+
+def enforce_permission(
+    session: Session, subject_id: uuid.UUID, permission_name: str
+) -> bool:
+    """Per-subject permission check for the kernel guard (the ``create_app`` seam).
+
+    Pass to ``create_app(permission_enforcer=enforce_permission)`` so a ``Policy``
+    that requires a ``Permission`` is enforced as a real grant (deny-by-default),
+    never silently degraded to the permission's role rank. Returns whether
+    *subject_id* currently holds *permission_name*.
+    """
+    return _service.has_permission(session, subject_id, permission_name)
+
+
+__all__ = ["enforce_permission", "require_permission"]

terp_cap_access-0.1.0/src/terp/capabilities/access/expansion.py

@@ -0,0 +1,67 @@
+"""Subject expansion — the seam that lets grants apply to *collections* of subjects.
+
+A :class:`~terp.capabilities.access.models.Grant` names a single ``subject_id``.
+That subject is usually a user, but the column is FK-less **by design**: a grant
+can just as well name a *group* of users (or any future principal-like subject).
+This module is the seam that makes such indirect grants effective without the
+access capability knowing who provides them:
+
+* a higher-layer capability (e.g. ``terp-cap-groups``) **registers** a
+  :data:`SubjectExpander` — a callable mapping one subject id to the extra
+  subject ids it speaks for (a user's group ids);
+* :meth:`~terp.capabilities.access.service.AccessService.has_permission` (the
+  single hot path behind both ``require_permission`` and the kernel guard's
+  ``permission_enforcer``) checks grants against the **expanded** subject set.
+
+The plug-in direction mirrors the kernel's scope-predicate registry (ADR 0017):
+the lower layer owns the registry and the check; the higher layer plugs in at
+import time; the lower layer never imports the higher. With no expander
+registered the set is exactly ``{subject_id}`` — the behaviour before this seam
+existed. An expander that raises propagates: the guarded request fails closed
+(500, no grant assumed) rather than silently narrowing to direct grants.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable, Iterable
+
+from sqlmodel import Session
+
+# Maps one subject to the additional subject ids whose grants it inherits
+# (e.g. a user -> the ids of the groups the user belongs to).
+SubjectExpander = Callable[[Session, uuid.UUID], Iterable[uuid.UUID]]
+
+_expanders: list[SubjectExpander] = []
+
+
+def register_subject_expander(expander: SubjectExpander) -> None:
+    """Register *expander* (idempotent: re-registering the same callable is a no-op).
+
+    Called at import time by the providing capability (the groups capability
+    registers its membership expander when its package is imported by entry-point
+    discovery), so installing the capability is all it takes.
+    """
+    if expander not in _expanders:
+        _expanders.append(expander)
+
+
+def reset_subject_expanders() -> None:
+    """Clear the registry (test isolation for suites that register a throwaway expander)."""
+    _expanders.clear()
+
+
+def subject_ids_for(session: Session, subject_id: uuid.UUID) -> set[uuid.UUID]:
+    """The full subject set whose grants *subject_id* holds: itself + every expansion."""
+    subjects = {subject_id}
+    for expander in _expanders:
+        subjects.update(expander(session, subject_id))
+    return subjects
+
+
+__all__ = [
+    "SubjectExpander",
+    "register_subject_expander",
+    "reset_subject_expanders",
+    "subject_ids_for",
+]

terp_cap_access-0.1.0/src/terp/capabilities/access/migrations/versions/71a140f9930e_create_access_tables.py

@@ -0,0 +1,50 @@
+"""create access tables
+
+Revision ID: 71a140f9930e
+Revises: 
+Create Date: 2026-06-26 20:38:59.309924
+
+"""
+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 = '71a140f9930e'
+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('access_grant',
+    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('subject_id', sa.Uuid(), nullable=False),
+    sa.Column('permission', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_grant')),
+    sa.UniqueConstraint('subject_id', 'permission', name='uq_access_grant_subject_permission')
+    )
+    with op.batch_alter_table('access_grant', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_access_grant_permission'), ['permission'], unique=False)
+        batch_op.create_index(batch_op.f('ix_access_grant_subject_id'), ['subject_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('access_grant', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_access_grant_subject_id'))
+        batch_op.drop_index(batch_op.f('ix_access_grant_permission'))
+
+    op.drop_table('access_grant')
+    # ### end Alembic commands ###

terp_cap_access-0.1.0/src/terp/capabilities/access/models.py

@@ -0,0 +1,33 @@
+"""The persisted access-grant table (RBAC permission grants).
+
+A :class:`Grant` is a single, immutable fact: *subject ``subject_id`` holds the
+named ``permission``*. Permissions are open, app-defined string tokens (e.g.
+``"billing:write"``, ``"reports:export"``) — the capability hard-codes **no**
+company module list. A composite unique constraint makes a grant idempotent: a
+subject holds a given permission at most once.
+
+``subject_id`` is an FK-less UUID on purpose: this low-layer capability must not
+import the higher-layer user table it references, so it stays a leaf the identity
+and app modules can depend on (never the reverse).
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field
+
+from terp.core import BaseTable
+
+
+class Grant(BaseTable, table=True):
+    __tablename__ = "access_grant"
+    __table_args__ = (
+        UniqueConstraint(
+            "subject_id", "permission", name="uq_access_grant_subject_permission"
+        ),
+    )
+
+    subject_id: uuid.UUID = Field(index=True)
+    permission: str = Field(max_length=128, index=True)

terp_cap_access-0.1.0/src/terp/capabilities/access/router.py

@@ -0,0 +1,53 @@
+"""Admin ``access`` (grants) router + the discoverable ``ModuleSpec``.
+
+**Admin-only** (``Policy`` requires ``ADMIN``): managing who holds which
+permission is itself a privileged action. Exposed as ``module`` so the kernel's
+entry-point discovery mounts it at ``/api/v1/access`` with no composition-root
+edit. Modules then gate their own actions with ``require_permission`` against the
+grants administered here.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter
+
+from terp.core import ModuleSpec, Page, PaginationDep, Policy, Roles, SessionDep
+
+from terp.capabilities.access.schemas import GrantCreate, GrantRead
+from terp.capabilities.access.service import AccessService
+
+router = APIRouter(tags=["access"])
+_service = AccessService()
+
+
+@router.get("/grants", response_model=Page[GrantRead])
+def list_grants(
+    subject_id: uuid.UUID, session: SessionDep, pagination: PaginationDep
+) -> Page[GrantRead]:
+    rows, total = _service.list_for(
+        session, subject_id, skip=pagination.skip, limit=pagination.limit
+    )
+    return Page[GrantRead].of(
+        [GrantRead.model_validate(row) for row in rows], total, pagination
+    )
+
+
+@router.post("/grants", response_model=GrantRead, status_code=201)
+def create_grant(payload: GrantCreate, session: SessionDep) -> GrantRead:
+    return GrantRead.model_validate(
+        _service.grant(session, payload.subject_id, payload.permission)
+    )
+
+
+@router.delete("/grants/{grant_id}", status_code=204)
+def delete_grant(grant_id: uuid.UUID, session: SessionDep) -> None:
+    _service.delete(session, grant_id)
+
+
+module = ModuleSpec(
+    name="access",
+    router=router,
+    policy=Policy(read_role=Roles.ADMIN, write_role=Roles.ADMIN),
+)

terp_cap_access-0.1.0/src/terp/capabilities/access/schemas.py

@@ -0,0 +1,32 @@
+"""Access DTOs. Grants are immutable, so there is no public ``*Update`` surface."""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+
+from sqlmodel import Field
+
+from terp.core import BaseSchema, BaseUpdateSchema
+
+
+class GrantCreate(BaseSchema):
+    subject_id: uuid.UUID
+    permission: str = Field(max_length=128)
+
+
+class GrantUpdate(BaseUpdateSchema):
+    """Grants are immutable (subject + permission) — nothing is updatable.
+
+    Present only to satisfy ``BaseService``'s ``UpdateT`` type parameter; the
+    admin router never exposes an update route.
+    """
+
+
+class GrantRead(BaseSchema):
+    id: uuid.UUID
+    subject_id: uuid.UUID
+    permission: str
+    version: int
+    created_at: datetime.datetime
+    updated_at: datetime.datetime

terp_cap_access-0.1.0/src/terp/capabilities/access/service.py

@@ -0,0 +1,97 @@
+"""Access service — RBAC permission grants + the effective-permission check.
+
+Grants are immutable (subject + permission), so writes are :meth:`grant`
+(idempotent) and :meth:`revoke`; reads build on the kernel ``BaseService`` so
+get / list / delete-by-id come for free. :meth:`has_permission` is the hot path
+the ``require_permission`` dependency calls on every guarded request; it checks
+the **expanded** subject set (the caller plus whatever registered subject
+expanders add — e.g. the groups capability's memberships), so a grant to a
+group is effective for its members with no extra call sites.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlmodel import Session, col, select
+
+from terp.core import AuditAction, BaseService
+
+from terp.capabilities.access.expansion import subject_ids_for
+from terp.capabilities.access.models import Grant
+from terp.capabilities.access.schemas import GrantCreate, GrantUpdate
+
+
+class AccessService(BaseService[Grant, GrantCreate, GrantUpdate]):
+    model = Grant
+
+    def _find(
+        self, session: Session, subject_id: uuid.UUID, permission: str
+    ) -> Grant | None:
+        return session.exec(
+            select(Grant).where(
+                Grant.subject_id == subject_id, Grant.permission == permission
+            )
+        ).first()
+
+    def grant(self, session: Session, subject_id: uuid.UUID, permission: str) -> Grant:
+        """Grant *permission* to *subject_id* (idempotent: a re-grant returns the existing row)."""
+        existing = self._find(session, subject_id, permission)
+        if existing is not None:
+            return existing
+        entity = Grant(subject_id=subject_id, permission=permission)
+        # A grant is a security-sensitive change: route it through the audited
+        # chokepoint so it lands an audit record (raw session writes do not).
+        return self._save(session, entity, AuditAction.CREATED)
+
+    def revoke(self, session: Session, subject_id: uuid.UUID, permission: str) -> bool:
+        """Revoke *permission* from *subject_id*; return whether a grant was removed."""
+        existing = self._find(session, subject_id, permission)
+        if existing is None:
+            return False
+        # Revoking a permission is audit-sensitive too: go through _remove so the
+        # DELETED record is emitted in the same transaction.
+        self._remove(session, existing)
+        return True
+
+    def has_permission(
+        self, session: Session, subject_id: uuid.UUID, permission: str
+    ) -> bool:
+        """True when *subject_id* holds *permission* (the deny-by-default check).
+
+        Checks the expanded subject set: a direct grant, or a grant to any subject
+        a registered expander maps the caller to (e.g. a group the user belongs
+        to). With no expander registered this is exactly the direct-grant check.
+        """
+        subjects = subject_ids_for(session, subject_id)
+        return (
+            session.exec(
+                select(Grant).where(
+                    col(Grant.subject_id).in_(subjects),
+                    Grant.permission == permission,
+                )
+            ).first()
+            is not None
+        )
+
+    def permissions_for(self, session: Session, subject_id: uuid.UUID) -> set[str]:
+        """Every permission *subject_id* holds — directly or through an expanded subject."""
+        subjects = subject_ids_for(session, subject_id)
+        rows = session.exec(
+            select(Grant.permission).where(col(Grant.subject_id).in_(subjects))
+        ).all()
+        return set(rows)
+
+    def list_for(
+        self, session: Session, subject_id: uuid.UUID, *, skip: int, limit: int
+    ) -> tuple[list[Grant], int]:
+        """Paginated grants for *subject_id* (admin listing)."""
+        return self._paginate(
+            session,
+            self.base_query().where(Grant.subject_id == subject_id),
+            skip=skip,
+            limit=limit,
+        )
+
+
+__all__ = ["AccessService"]