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 TTL cache (actor -> [GroupMembership], `(group_id, namespace_id) -> action_set
    • trails, (group_id, namespace_type, customer_id) -> action_set
    • trails) with fine-grained invalidation hooks fired on group-membership / role / assignment change. 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

  • MembershipInvalidatePayload, AssignmentInvalidatePayload, RoleInvalidatePayload -- typed Pydantic models for the three {ns}.acl.*.invalidate NATS subjects. Wire format is single-source: every publisher (admin endpoints, agent self-mutations) and every subscriber (cache subscribers in any consuming app) speaks these models.

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,
    ttl_seconds=60,
)

# 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.

Project links

Data verified by PyPI on Sep 7, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.42.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for pace from gravatar.com pace

Credits

Author: pace

GitHub Statistics

Data verified by PyPI on Sep 7, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Provides Extra

bus

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

3tears_agent_acl-0.33.0.tar.gz (158.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

3tears_agent_acl-0.33.0-py3-none-any.whl (103.4 kB view details)

Uploaded Python 3

File details

Details for the file 3tears_agent_acl-0.33.0.tar.gz.

File metadata

  • Download URL: 3tears_agent_acl-0.33.0.tar.gz
  • Upload date:
  • Size: 158.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for 3tears_agent_acl-0.33.0.tar.gz
Algorithm Hash digest
SHA256 b022ff5ef7f9c63b8532c45a5fed1751f9883c3d2792590fbaeff6d39491e7c9
MD5 7aa24096efa363d4ff0ca8c06241c8e1
BLAKE2b-256 b26f54500cf22510dc831099e26b3e2e9fbae493a24454e7a599c73bb81772ec

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_acl-0.33.0.tar.gz:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file 3tears_agent_acl-0.33.0-py3-none-any.whl.

File metadata

File hashes

Hashes for 3tears_agent_acl-0.33.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2d15781cfdb67c22d7f071dea72cf68793c15e9b0100aafd41a185355c872173
MD5 645abecd27054de32e31b181f769e679
BLAKE2b-256 91865d9e5af56d00619bff53845336d07454a990f8b24669b461dc6a7f9229bb

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_acl-0.33.0-py3-none-any.whl:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.42.0

2 files

0.41.4

2 files

0.41.3

2 files

0.41.2

2 files

0.41.1

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.0

2 files

0.35.1

2 files

0.35.0

2 files

0.34.0

2 files

This release

0.33.0 This release

2 files

0.32.1

2 files

0.32.0

2 files

0.31.0

2 files

0.30.1

2 files

0.30.0

2 files

0.29.0

2 files

0.28.0

2 files

0.27.0

2 files

0.26.1

2 files

0.26.0

2 files

0.25.0

2 files

0.24.7

2 files

0.24.6

2 files

0.24.5

2 files

0.24.4

2 files

0.24.3

2 files

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.11

2 files

0.23.10

2 files

0.23.9

2 files

0.23.8

2 files

0.23.7

2 files

0.23.6

2 files

0.23.5

2 files

0.23.3

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.4

2 files

0.19.3

2 files

0.19.2

2 files

0.19.1

2 files

0.19.0

2 files

0.18.0

2 files

0.17.9

2 files

0.17.8

2 files

0.17.7

2 files

0.17.6

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page