sentrykit 0.1.0rc1__py3-none-any.whl

sentrykit/context.py

@@ -0,0 +1,393 @@
+"""Ambient authorization context: who is acting, and under what circumstances.
+
+A protected callable almost never receives the principal as an argument — a Flask view takes
+a request, an agent tool takes the arguments the model proposed, a background job takes
+none. Threading a principal through every signature between the boundary and the call would
+be the tax that stops teams from protecting the inner functions at all.
+
+So sentrykit makes the principal ambient instead: a context provider calls
+:func:`establish` once at the boundary, and ``@protect`` reads the ambient principal
+wherever the callable happens to live. Three rules follow from that, and they are load-bearing:
+
+* An explicit ``_as=`` on the call beats the ambient principal.
+* **No principal means deny.** Not "run unauthenticated", not "skip the check".
+* ``ContextVar`` values propagate across ``await`` and across ``asyncio.to_thread``, but
+  *not* across a bare ``ThreadPoolExecutor.submit``. Offloading through an executor without
+  :func:`bind_context` would silently lose the principal — and, because of the previous
+  rule, fail closed rather than fail open.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Generator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar, Token, copy_context
+from datetime import datetime
+from types import MappingProxyType, TracebackType
+from typing import Final, Literal, ParamSpec, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from sentrykit.cedar import EntityRef
+from sentrykit.constraints import ConstraintSet
+from sentrykit.envelope import set_last_envelope
+from sentrykit.errors import NoContext
+
+__all__ = [
+    "Channel",
+    "ContextScope",
+    "Invocation",
+    "Principal",
+    "bind_context",
+    "clear_context",
+    "current_environment",
+    "current_principal",
+    "establish",
+    "principal_context",
+    "require_principal",
+]
+
+P = ParamSpec("P")
+T = TypeVar("T")
+V = TypeVar("V")
+
+_logger: Final = logging.getLogger("sentrykit.context")
+
+Channel = Literal["http", "agent", "internal"]
+"""Where the invocation came from. Policies can condition on it via ``context.channel``."""
+
+WILDCARD_ACTION: str = "*"
+"""Key under which a :class:`Principal` may carry constraints that apply to every action."""
+
+_DEFAULT_CHANNEL: Final = "internal"
+"""Channel assumed when a provider established none — a plain in-process call."""
+
+_EMPTY_ENVIRONMENT: Final[Mapping[str, object]] = MappingProxyType({})
+"""The environment seen before anything is established.
+
+A read-only proxy rather than a plain ``dict``, so a caller that pokes at the ambient
+environment cannot mutate the default that every other context starts from.
+"""
+
+_principal_var: ContextVar[Principal | None] = ContextVar("sentrykit_principal", default=None)
+_environment_var: ContextVar[Mapping[str, object]] = ContextVar(
+    "sentrykit_environment", default=_EMPTY_ENVIRONMENT
+)
+
+
+def _restore(variable: ContextVar[V], token: Token[V], empty: V) -> None:
+    """Reset one context variable, clearing it outright if its token belongs elsewhere.
+
+    A scope reset from a different ``Context`` than the one that established it — a provider
+    whose teardown hook runs on another task — cannot use its token. Leaving the
+    establishment in place would be failing *open*, so the variable is cleared instead and
+    the anomaly is logged.
+
+    Args:
+        variable: The context variable to restore.
+        token: The token captured when the variable was set.
+        empty: The value meaning "nothing established", used when the token is unusable.
+    """
+    try:
+        variable.reset(token)
+    except ValueError:
+        variable.set(empty)
+        _logger.warning(
+            "Context scope for %s was reset outside its originating context; cleared instead",
+            variable.name,
+        )
+
+
+class Principal(BaseModel):
+    """Who is acting, as sentrykit sees them.
+
+    A principal is a Cedar entity plus the argument constraints that have been granted to
+    them. Roles, teams and delegation edges are all just parent edges: Cedar computes the
+    transitive closure, which is how a multi-hop relationship — user in team, team on
+    project, project owns resource — gets resolved by policy rather than by a chain of
+    ``if`` statements in the application.
+
+    Attributes:
+        id: The entity id.
+        type: The entity type. ``User`` covers the common case; an agent acting for a human
+            is still modelled as that human, with the delegation recorded in
+            :attr:`attributes`.
+        roles: Convenience for the most common parent edge. Each entry ``r`` becomes a
+            parent ``Role::"r"``.
+        parents: Any other direct parent edges — teams, projects, delegation targets.
+        attributes: Cedar attributes for this principal, snapshotted at decision time.
+            Values are coerced for Cedar, so ``None`` entries are dropped.
+        constraints: Argument constraints keyed by action. The key may be a full uid
+            (``Action::"tool.search"``), a bare action id (``tool.search``), or ``"*"`` for
+            constraints that apply to every action. In a wired application these are
+            materialized from the grant store rather than constructed by hand.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str
+    type: str = "User"
+    roles: tuple[str, ...] = ()
+    parents: tuple[EntityRef, ...] = ()
+    attributes: dict[str, object] = Field(default_factory=dict)
+    constraints: dict[str, ConstraintSet] = Field(default_factory=dict)
+
+    @property
+    def uid(self) -> EntityRef:
+        """This principal as a Cedar entity reference."""
+        return EntityRef(self.type, self.id)
+
+    def all_parents(self) -> tuple[EntityRef, ...]:
+        """Every parent edge — :attr:`roles` expanded to ``Role::"..."`` plus :attr:`parents`."""
+        # A dict keyed by the reference deduplicates while preserving first-seen order, so a
+        # role also listed explicitly in ``parents`` produces one edge rather than two.
+        edges: dict[EntityRef, None] = {}
+        for role in self.roles:
+            edges.setdefault(EntityRef("Role", role), None)
+        for parent in self.parents:
+            edges.setdefault(parent, None)
+        return tuple(edges)
+
+    def constraints_for(self, action: EntityRef) -> ConstraintSet:
+        """Resolve the argument constraints that apply to ``action``.
+
+        Lookup runs from least to most specific: the ``"*"`` wildcard set first, then the
+        bare action id, then the full uid — each layered over the previous, so a
+        wildcard baseline can be refined per action.
+
+        Args:
+            action: The action being authorized.
+
+        Returns:
+            The merged constraint set, empty when nothing applies.
+        """
+        resolved = ConstraintSet()
+        if not self.constraints:
+            return resolved
+        for key in (WILDCARD_ACTION, action.id, str(action)):
+            layer = self.constraints.get(key)
+            if layer is not None:
+                resolved = resolved.merged_with(layer)
+        return resolved
+
+
+class Invocation(BaseModel):
+    """One normalized call, as the core sees it — independent of how it arrived.
+
+    This is the object architecture §1 describes: the decorator supplies the action and the
+    proposed arguments, a context provider supplies the principal and the environment, and
+    nothing downstream can tell whether it came from an HTTP route, an MCP tool dispatch, or
+    a plain function call.
+
+    Attributes:
+        id: Correlation id, shared by the Cedar result, the operational logs and the audit
+            record.
+        principal: Who is acting.
+        action: What they propose to do.
+        resource: What they propose to do it to.
+        proposed: The arguments as supplied — untrusted input, before any filtering.
+        environment: Cedar request context: ``now``, ``channel``, request id, auth strength,
+            delegation chain, break-the-glass flag.
+        callable_name: Qualified name of the protected callable, for diagnostics.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    principal: Principal
+    action: EntityRef
+    resource: EntityRef
+    proposed: dict[str, object] = Field(default_factory=dict)
+    environment: dict[str, object] = Field(default_factory=dict)
+    callable_name: str = ""
+
+    @property
+    def channel(self) -> str:
+        """The channel from :attr:`environment`, defaulting to ``internal``."""
+        return str(self.environment.get("channel", _DEFAULT_CHANNEL))
+
+    @property
+    def now(self) -> datetime | None:
+        """The decision timestamp from :attr:`environment`, if one was established."""
+        established = self.environment.get("now")
+        return established if isinstance(established, datetime) else None
+
+
+class ContextScope:
+    """The handle :func:`establish` returns: undo the establishment when the boundary ends.
+
+    Usable two ways, because the two boundaries need different shapes. A framework hook that
+    has no enclosing block — Flask's ``before_request``, an MCP dispatch callback — keeps the
+    handle and calls :meth:`reset`. Everything else uses it as a context manager, which
+    resets even when the body raises.
+
+    Example:
+        ```python
+        with establish(principal, channel="agent"):
+            await run_tool()
+        ```
+    """
+
+    __slots__ = ("_environment_token", "_principal_token", "_reset")
+
+    def __init__(
+        self,
+        principal_token: Token[Principal | None],
+        environment_token: Token[Mapping[str, object]],
+    ) -> None:
+        """Capture the tokens needed to undo one establishment.
+
+        Constructed by :func:`establish`; there is no reason for application code to build
+        one directly.
+
+        Args:
+            principal_token: Token returned when the principal was set.
+            environment_token: Token returned when the environment was set.
+        """
+        self._principal_token = principal_token
+        self._environment_token = environment_token
+        self._reset = False
+
+    def reset(self) -> None:
+        """Restore the principal and environment that were ambient before establishment.
+
+        Idempotent: resetting an already-reset scope does nothing.
+        """
+        if self._reset:
+            return
+        # Mark first: a failed restore must not leave the scope re-resettable, since the
+        # fallback below has already put the context somewhere safe.
+        self._reset = True
+        _restore(_principal_var, self._principal_token, None)
+        _restore(_environment_var, self._environment_token, _EMPTY_ENVIRONMENT)
+
+    def __enter__(self) -> ContextScope:
+        """Return this scope, for use as a context manager."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Reset the scope, whether or not the block raised."""
+        self.reset()
+
+
+def establish(principal: Principal, **environment: object) -> ContextScope:
+    """Make ``principal`` the ambient principal for this context.
+
+    Called by a context provider at the framework boundary. The environment keys become the
+    Cedar request context, so policies can condition on them directly.
+
+    Args:
+        principal: Who the subsequent protected calls are acting as.
+        **environment: Request environment — ``channel``, ``request_id``, ``auth_strength``,
+            ``break_glass``, a delegation chain, and anything else the policy pack expects.
+            ``now`` is filled in by the engine at decision time unless supplied here.
+
+    Returns:
+        A scope handle. Use it as a context manager, or call :meth:`ContextScope.reset` when
+        the boundary has no enclosing block.
+    """
+    principal_token = _principal_var.set(principal)
+    # Snapshot behind a read-only proxy: the environment a decision was made against should
+    # not be able to change under the decision.
+    environment_token = _environment_var.set(MappingProxyType(dict(environment)))
+    return ContextScope(principal_token, environment_token)
+
+
+@contextmanager
+def principal_context(principal: Principal, **environment: object) -> Generator[None, None, None]:
+    """Establish ``principal`` for the duration of a ``with`` block.
+
+    The generator-based twin of :func:`establish`, for callers who prefer an explicit
+    context manager over a handle that happens to be one.
+
+    Args:
+        principal: Who the block is acting as.
+        **environment: Request environment, as for :func:`establish`.
+
+    Yields:
+        ``None``, with the context established.
+    """
+    with establish(principal, **environment):
+        yield
+
+
+def current_principal() -> Principal | None:
+    """Return the ambient principal, or ``None`` if none has been established."""
+    return _principal_var.get()
+
+
+def require_principal(action: str) -> Principal:
+    """Return the ambient principal, or refuse the call.
+
+    Args:
+        action: The action being attempted, for the error message.
+
+    Returns:
+        The ambient principal.
+
+    Raises:
+        NoContext: If no principal is ambient. This is the fail-closed rule, and it holds
+            regardless of ``fail_mode``: an engine that cannot tell who is calling
+            has nothing to authorize.
+    """
+    principal = _principal_var.get()
+    if principal is None:
+        # A missing principal is normal operation for an unauthenticated caller, not an
+        # operator-actionable error — hence INFO, per the logging standards.
+        _logger.info("No principal in context for action %s; denying", action)
+        raise NoContext(action)
+    return principal
+
+
+def current_environment() -> Mapping[str, object]:
+    """Return the ambient request environment, empty when nothing was established."""
+    return _environment_var.get()
+
+
+def clear_context() -> None:
+    """Drop the ambient principal, the environment, and the last decision envelope.
+
+    For tests and for long-lived workers that reuse a context between units of work. The
+    envelope goes too: a worker that has finished one unit of work should not be able to
+    report the previous one's decision as if it were its own.
+    """
+    _principal_var.set(None)
+    _environment_var.set(_EMPTY_ENVIRONMENT)
+    set_last_envelope(None)
+
+
+def bind_context(fn: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> Callable[[], T]:
+    """Bind a call to a copy of the current context, for offload to a thread pool.
+
+    ``ContextVar`` values follow ``await`` and ``asyncio.to_thread`` on their own, so most
+    code needs nothing. A bare ``ThreadPoolExecutor.submit`` or ``loop.run_in_executor`` is
+    the exception: the worker thread starts from an empty context, the ambient principal is
+    gone, and every protected call inside it denies. Wrapping the call here carries the
+    context across.
+
+    Example:
+        ```python
+        executor.submit(bind_context(reconcile_orders, batch_id))
+        ```
+
+    Args:
+        fn: The callable to run in the other thread.
+        *args: Positional arguments for ``fn``.
+        **kwargs: Keyword arguments for ``fn``.
+
+    Returns:
+        A zero-argument thunk that runs ``fn`` inside a copy of the calling context.
+    """
+    context = copy_context()
+
+    def run_bound() -> T:
+        """Run the bound call inside the copied context."""
+        return context.run(fn, *args, **kwargs)
+
+    return run_bound

sentrykit/decorator.py

@@ -0,0 +1,252 @@
+"""``@protect`` — one decorator, and N context providers behind it.
+
+Everything a framework contributes is a context provider. Everything a developer writes is
+this decorator. A Flask view, a background reconciliation job and an MCP tool are all
+guarded by the same three lines of code, because the decorator only supplies the *action*
+and the *proposed arguments*; who is acting comes from the ambient context.
+
+```python
+@protect(action='Action::"tool.search_orders"', resource='Tool::"orders"')
+async def search_orders(customer_id: str, limit: int = 10) -> list[Order]: ...
+```
+
+The wrapper is signature-preserving, so type checkers, IDEs, and — importantly — FastAPI's
+and Pydantic-AI's signature introspection see the original function.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Final, ParamSpec, TypeVar, cast, overload
+
+from sentrykit.cedar import EntityRef
+from sentrykit.context import Principal, current_principal
+from sentrykit.engine import ArgumentSpec, Governor, derive_action, get_governor
+from sentrykit.errors import ConfigurationError, NoContext
+
+__all__ = [
+    "AS_KEYWORD",
+    "ProtectedMeta",
+    "is_protected",
+    "protect",
+    "protected_meta",
+]
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+_P = ParamSpec("_P")
+_T = TypeVar("_T")
+
+AS_KEYWORD: str = "_as"
+"""Call keyword that overrides the ambient principal for a single invocation."""
+
+_META_ATTR: Final = "__sentrykit__"
+"""Attribute under which :class:`ProtectedMeta` is stashed on the wrapper."""
+
+_ABSENT: Final = object()
+"""Sentinel distinguishing ``_as=None`` from no ``_as`` at all."""
+
+
+@dataclass(frozen=True, slots=True)
+class ProtectedMeta:
+    """What ``@protect`` records on the callable it wraps.
+
+    Attached as ``__sentrykit__`` so that tooling can introspect a protected callable without
+    calling it — which is exactly what the agent-side ``list_tools`` filtering does to decide
+    whether a principal should be shown a tool at all.
+
+    Attributes:
+        action: The action this callable is authorized as.
+        resource: The declared resource, or ``None`` to let the governor synthesize one.
+        spec: The cached argument spec.
+        governor: A governor pinned to this callable, or ``None`` to use the process default
+            at call time.
+    """
+
+    action: EntityRef
+    resource: EntityRef | None
+    spec: ArgumentSpec
+    governor: Governor | None
+
+
+@overload
+def protect(fn: Callable[P, T], /) -> Callable[P, T]: ...
+
+
+@overload
+def protect(
+    *,
+    action: str | EntityRef | None = None,
+    resource: str | EntityRef | None = None,
+    governor: Governor | None = None,
+) -> Callable[[Callable[P, T]], Callable[P, T]]: ...
+
+
+def protect(
+    fn: Callable[P, T] | None = None,
+    /,
+    *,
+    action: str | EntityRef | None = None,
+    resource: str | EntityRef | None = None,
+    governor: Governor | None = None,
+) -> Callable[P, T] | Callable[[Callable[P, T]], Callable[P, T]]:
+    """Guard a callable with pre-action authorization.
+
+    On every call the wrapper resolves the principal, binds the proposed arguments to
+    parameter names, and hands both to the governor, which gates, filters, defaults,
+    validates and only then invokes. Sync and async callables are both supported; the
+    wrapper matches whichever it wraps.
+
+    Usable bare (``@protect``) or with arguments (``@protect(action=...)``).
+
+    The principal comes from the ambient context established by a provider. It can be
+    overridden for one call by passing ``_as=<Principal>``, which the wrapper strips before
+    binding — useful for a scheduled job that acts for a specific user, and for tests.
+    Because the wrapper preserves the wrapped signature, a strictly type-checked caller
+    passing ``_as=`` needs a ``type: ignore[call-arg]``; prefer
+    :func:`~sentrykit.context.establish` where that matters.
+
+    **No ambient principal and no ``_as=`` means the call is denied**, not run unguarded.
+    That is the fail-closed rule, and it is why forgetting to wire a provider surfaces
+    immediately rather than as a silent hole.
+
+    Args:
+        fn: The callable, when used bare as ``@protect``.
+        action: The Cedar action. Accepts a full uid (``Action::"tool.search"``) or a bare
+            id, which is read as an ``Action``. Defaults to
+            ``Action::"<module>.<qualname>"``.
+        resource: The Cedar resource. Accepts a full uid or a bare id read as a
+            ``Resource``. Defaults to a resource derived from the action, so that a callable
+            with no natural resource still fits Cedar's principal/action/resource model.
+        governor: Pin a governor to this callable. Defaults to the process-installed one,
+            resolved at call time so wiring order does not matter.
+
+    Returns:
+        The guarded callable, with the original signature and an attached
+        :class:`ProtectedMeta`.
+
+    Raises:
+        ConfigurationError: If ``action`` or ``resource`` cannot be parsed, or the callable's
+            signature cannot be introspected.
+    """
+
+    def decorate(target: Callable[_P, _T]) -> Callable[_P, _T]:
+        spec = ArgumentSpec.from_callable(target)
+        meta = ProtectedMeta(
+            action=(
+                EntityRef.parse(action, default_type="Action")
+                if action is not None
+                else derive_action(target)
+            ),
+            resource=(
+                EntityRef.parse(resource, default_type="Resource") if resource is not None else None
+            ),
+            spec=spec,
+            governor=governor,
+        )
+        if spec.is_async:
+            asynchronous = _wrap_async(cast("Callable[_P, Awaitable[Any]]", target), meta)
+            wrapped = cast("Callable[_P, _T]", asynchronous)
+        else:
+            wrapped = _wrap_sync(target, meta)
+        setattr(wrapped, _META_ATTR, meta)
+        return wrapped
+
+    if fn is not None:
+        return decorate(fn)
+    return decorate
+
+
+def protected_meta(fn: object) -> ProtectedMeta | None:
+    """Return the metadata ``@protect`` attached to ``fn``, if it is protected.
+
+    Args:
+        fn: Any object, typically a callable.
+
+    Returns:
+        The metadata, or ``None`` when ``fn`` is not protected.
+    """
+    meta = getattr(fn, _META_ATTR, None)
+    return meta if isinstance(meta, ProtectedMeta) else None
+
+
+def is_protected(fn: object) -> bool:
+    """Whether ``fn`` carries a ``@protect`` wrapper."""
+    return protected_meta(fn) is not None
+
+
+def _resolve_principal(meta: ProtectedMeta, override: object) -> Principal:
+    """Decide who this call acts as.
+
+    Args:
+        meta: The protected callable's metadata, for the error message.
+        override: Whatever came in as ``_as=``, or the absent sentinel.
+
+    Returns:
+        The explicit override when one was passed, otherwise the ambient principal.
+
+    Raises:
+        ConfigurationError: If ``_as=`` was passed something other than a
+            :class:`~sentrykit.context.Principal`.
+        NoContext: If nothing was passed and no principal is ambient. Fail-closed, and
+            deliberately independent of ``fail_mode``: an engine that cannot
+            tell who is calling has nothing to authorize.
+    """
+    if override is not _ABSENT:
+        if not isinstance(override, Principal):
+            raise ConfigurationError(
+                f"{AS_KEYWORD}= must be a Principal, got {type(override).__name__}"
+            )
+        return override
+    principal = current_principal()
+    if principal is None:
+        raise NoContext(str(meta.action))
+    return principal
+
+
+def _wrap_sync(
+    fn: Callable[P, T],
+    meta: ProtectedMeta,
+) -> Callable[P, T]:
+    """Build the synchronous wrapper for ``fn``."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        # Stripped before binding: ``_as`` is sentrykit's keyword, not the callable's.
+        principal = _resolve_principal(meta, kwargs.pop(AS_KEYWORD, _ABSENT))
+        active = meta.governor or get_governor()
+        plan = active.plan(
+            meta.spec,
+            principal=principal,
+            action=meta.action,
+            resource=meta.resource,
+            proposed=meta.spec.bind(args, kwargs),
+        )
+        return active.invoke(fn, plan)
+
+    return wrapper
+
+
+def _wrap_async(
+    fn: Callable[P, Awaitable[T]],
+    meta: ProtectedMeta,
+) -> Callable[P, Awaitable[T]]:
+    """Build the asynchronous wrapper for ``fn``."""
+
+    @functools.wraps(fn)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        principal = _resolve_principal(meta, kwargs.pop(AS_KEYWORD, _ABSENT))
+        active = meta.governor or get_governor()
+        plan = active.plan(
+            meta.spec,
+            principal=principal,
+            action=meta.action,
+            resource=meta.resource,
+            proposed=meta.spec.bind(args, kwargs),
+        )
+        return await active.ainvoke(fn, plan)
+
+    return wrapper