3tears-agent-acl

Shared RBAC primitives for the 3tears platform: evaluator, cache, canonical Collections, loader adapters, and NATS invalidation payload models.

Purpose

Single source of truth for "can actor do action on namespace" decisions PLUS the persistence layer that feeds them. The same pure-Python evaluator, canonical Collections, and loader adapters run in every consuming application, so authorization answers are byte-identical across processes and one set of unit tests covers every caller.

The Collections, loaders, and invalidation models are reusable across any 3tears app. The package supersedes per-resource ACL code paths (namespace_grants, workspace-specific checks, tool-access fnmatch lists).

Public API

Exports (see src/threetears/agent/acl/__init__.py):

Evaluation

• evaluate_decision(ctx, *, cache: AclCache) -> bool -- fast yes/no hot path. The cache is consulted for membership and per-namespace contribution layers on every call, falling back to its loaders only on cache miss; production hit rate against repeated authz checks for the same (actor, namespace) is ~100% within the cache TTL.
• evaluate_with_trail(ctx, *, cache) -> EvaluationResult -- introspection path returning every (group, assignment, role) -> contributed_actions chain plus limiting_side for user×agent intersection queries. Uses the same cache layers as evaluate_decision; trails are stored alongside the action set so successive decision-mode and trail-mode calls for the same actor + namespace serve from cache.
• evaluate_file_access(*, namespace, user_id, agent_id, path, direction, cache) -> bool -- workspace path-glob gate; same cache semantics.
• authorize(*, namespace_collection, namespace_name, action, user_id, agent_id, cache) -> EvaluationResult -- canonical authorization primitive every app's resource-typed wrapper is built on. Looks up the namespace by name, runs evaluate_with_trail through the cache, raises generic AccessDenied on deny / NamespaceNotFound on missing row.
• authorize_with_trail -- variant returning (result, ns_entity) for wrappers needing the entity.
• AccessDenied / NamespaceNotFound -- generic + namespace-miss exception classes; per-resource wrappers subclass AccessDenied to carry typed catching at endpoint code (e.g. MemoryAccessDenied, DatasourceAccessDenied).
• AclCache -- three-layer in-process cache (actor -> [GroupMembership], `(group_id, namespace_id) -> action_set
  • trails, (group_id, namespace_type, customer_id) -> action_set
  • trails). Nothing in it ages: it is evicted row by row from the access tables' row broadcasts and follows their write generations (generation_follow.follow_access_tables), and serves what it holds only while those watches run. The ActorMembershipEntry` carries the full memberships tuple so the evaluator's cross-customer + member-type filter runs against cached state.

Persistence

• GroupCollection, GroupMemberCollection, RoleCollection, RoleAssignmentCollection, NamespaceCollection -- three-tier SchemaBackedCollection subclasses fronting the canonical RBAC tables (groups, group_members, roles, role_assignments, namespaces). Schemas use canonical RBAC names with no deploy-specific schema prefix; the prefix is set on the L3 pool's search_path, not in the schema name on the Collection.
• GroupEntity, GroupMemberEntity, RoleEntity, RoleAssignmentEntity, NamespaceEntity -- BaseEntity subclasses; four use composite primary keys post-row_scope partitioning ((row_scope, id) for groups / role_assignments / namespaces; (group_id, id) for group_members).
• CollectionMembershipLoader, CollectionGrantLoader -- concrete loader adapters satisfying the MembershipLoader / GrantLoader Protocols, wired against the canonical Collections.

Invalidation

• generation_follow.follow_access_tables(registry, cache, reader) -- binds an AclCache to the access tables' row broadcasts and follows their write generations (epoch-task-06); the only invalidation there is. generation_follow.follow_caller_access_cache(registry, cache, reader) does the same for a CallerAccessCache. Both return an AccessTableFollowing whose stop() undoes the bind and the follow.
• threetears.agent.acl.generation_follow needs the follow extra: install 3tears-agent-acl[follow], which brings 3tears-epoch and the NATS client. The watches are threetears.epoch.TableFollower, the family's follower for any table; the plain install does not include it, and importing the module without it raises ModuleNotFoundError.
• evict_after_rbac_write(cache, member_actors=..., group_ids=...) -- what a helper that writes an rbac row evicts from its own cache at once.

Answers shared per access shape

A person's access is a function of their direct membership rows alone (roles go to groups, never people), so an answer derived once for a set of groups serves everyone with it.

• AccessShape.of(rows) -- a person's shape: sorted (group_id, membership customer_id).
• ShapeActors(inner_loader) -- the membership loader the AclCache reads through; actor_for(shape) returns an actor whose memberships are the shape, so an answer derived as that actor is right for everyone with the shape. A shape it no longer holds is refused (LookupError), never read as empty.
• access_shapes.access_footprint(cache, shape=, agent_ids=) -- the groups (through nesting), roles and agents an answer for a shape can reach: what a change must name to make the answer stale.
• AccessShapeAnswers(registry, config, table_name=..., acl_cache=..., actors=..., dependencies=...) -- one answer per (kind, customer, shape) in L1 and L2, derived once across replicas (in-process gate and cross-pod build lock). answer(kind=, customer_id=, shape=, context=, agent_ids=, compute=) reads L1, then L2, then derives; compute(actor_id) evaluates as the shape's actor.
• ShapeDependencies(registry, tables) -- what the answers are checked against on every read: each table's generation as applied here, and the generation of the last change reaching each group, role and agent. A change drops only the answers whose footprint it reaches, on every tier and every replica that hears it. Followed with generation_follow.follow_access_shape_answers(registry, dependencies, reader). Answers are served and kept only while the tables are followed and the AclCache is followed too (AclCache.followed): a scratch access cache drops nothing it holds.
• generation_follow.follow_caller_memberships(registry, cache, reader) -- a CallerAccessCache of each person's own shape, dropped only by a group_members row naming them.

Value types & protocols

• Value types: Group, GroupMembership, Role, RoleAssignment, Namespace, EvaluationContext, EvaluationResult, Trail.
• Enums: ActorType, MemberType, ScopeType, LimitingSide.
• I/O protocols: GrantLoader, MembershipLoader -- callers may implement these against any persistence layer; the canonical Collection*Loader adapters above are the reference impls.

Consuming the package from a 3tears app

Each app constructs the canonical Collections against its own L3 pool (direct asyncpg in a server-style deployment, NATS-proxied L3 in each agent pod) and wires the canonical loader adapters + cache. Deployment-specific admin query shapes (dynamic list_by_filter / per-cardinality counts / multi-table discovery JOINs) live on consuming-app subclasses.

from threetears.agent.acl import (
    AclCache,
    CollectionGrantLoader,
    CollectionMembershipLoader,
    EvaluationContext,
    GroupCollection,
    GroupMemberCollection,
    NamespaceCollection,
    RoleAssignmentCollection,
    RoleCollection,
    evaluate_decision,
)

# 1. construct Collections against your registry / L3 pool
group_collection = GroupCollection(registry=registry, config=core_config)
group_member_collection = GroupMemberCollection(registry=registry, config=core_config)
role_collection = RoleCollection(registry=registry, config=core_config)
role_assignment_collection = RoleAssignmentCollection(registry=registry, config=core_config)
namespace_collection = NamespaceCollection(registry=registry, config=core_config)

# 2. wire the canonical loaders
membership_loader = CollectionMembershipLoader(collection=group_member_collection)
grant_loader = CollectionGrantLoader(
    assignment_collection=role_assignment_collection,
    role_collection=role_collection,
    group_collection=group_collection,
)

# 3. build the cache
cache = AclCache(
    membership_loader=membership_loader,
    grant_loader=grant_loader,
)

# 4. evaluate
ctx = EvaluationContext(
    namespace=target_namespace,
    action="read",
    user_id=user_id,
    agent_id=agent_id,
)
allowed = await evaluate_decision(
    ctx,
    membership_loader=membership_loader,
    grant_loader=grant_loader,
)

Implicit ownership: if namespace.owner_agent_id == ctx.agent_id, the agent side short-circuits to full permissions with no group lookup or assignment query. Ownership is a property of the namespace row, never a grant.