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 3, 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.41.4)

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 3, 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.32.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.32.0-py3-none-any.whl (103.4 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: 3tears_agent_acl-0.32.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.32.0.tar.gz
Algorithm Hash digest
SHA256 07c9c8be32af0a031acc4626258b4aa9ef3a5396ca2f5523a4307dacb1619bb9
MD5 53eb4e673ca751d24fd6b642cf5dff22
BLAKE2b-256 3c2c9c9d968c48d66dfc148e138926dc4b211b09fe3c3d211601a8fb67e36f60

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for 3tears_agent_acl-0.32.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f2e66e0b57036c48e2f77fa9741e963a0d79ef346ec0901895222e1d0e7b12a4
MD5 c0f12c2f18eef326fb280043eb2caf8a
BLAKE2b-256 ca096837e8fda0d37dc065bb77f65832e599c93884663b4ec0231b2cea091eff

See more details on using hashes here.

Provenance

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

This release

0.32.0 This release

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