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 Aug 10, 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 Aug 10, 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.23.11.tar.gz (107.3 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.23.11-py3-none-any.whl (74.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: 3tears_agent_acl-0.23.11.tar.gz
  • Upload date:
  • Size: 107.3 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.23.11.tar.gz
Algorithm Hash digest
SHA256 37dda59f547e63ebdd7ba87d4832ae45f5ae07d8bd11274364db9c5096f363f3
MD5 51777270b2370790b629693c84f30f07
BLAKE2b-256 95764a27a5368c13a55a35c557f3ff0377d8afe6bf11ae0ecf53474d0c898219

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_acl-0.23.11.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.23.11-py3-none-any.whl.

File metadata

File hashes

Hashes for 3tears_agent_acl-0.23.11-py3-none-any.whl
Algorithm Hash digest
SHA256 4a55cfb819ee84ee84699202fab5a105695b4f59c0014d3ea7ebd77341003341
MD5 26776b813aa1e6288aef6ff6d61df372
BLAKE2b-256 e4c0ed6732a0597f29837e492cded91dbf9ed7f6d9ddc6cc42339bcc90fd8a0d

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_acl-0.23.11-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

0.33.0

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

This release

0.23.11 This release

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