跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

cognee-permissions

Use when working with cognee's permission system — understanding or changing how users, roles, and tenants get access to datasets, how ACL grants work, where permissions are enforced in add/cognify/search/delete, and how the grant records surface in the memory-provenance view.

topoteretes · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add topoteretes/cognee --skill cognee-permissions

技能说明


name: cognee-permissions description: Use when working with cognee's permission system — understanding or changing how users, roles, and tenants get access to datasets, how ACL grants work, where permissions are enforced in add/cognify/search/delete, and how the grant records surface in the memory-provenance view.

The cognee permission system

The master switch

ENABLE_BACKEND_ACCESS_CONTROL decides whether any of this runs:

  • true (default): multi-tenant mode. Every API call requires auth, every dataset operation is permission-checked, and each user+dataset pair gets isolated graph/vector/relational databases (tracked in the DatasetDatabase model, supported backends: Kuzu, LanceDB, SQLite, Postgres).
  • false: single-user mode. Permission checks short-circuit to allowed, there is no per-dataset isolation, and every user's operations resolve to the same shared databases and datasets. Authentication is a separate knob: REQUIRE_AUTHENTICATION. Unset, it inherits this switch (so turning access control off also turns auth off) — but if REQUIRE_AUTHENTICATION=true is set, endpoints still demand a login; authenticated users are identified but not isolated, all pointing at the same data. The reverse misconfiguration (REQUIRE_AUTHENTICATION=false with access control on) is ignored: auth is forced on with a warning, because multi-tenant isolation is meaningless without identity (get_authenticated_user.py).

The core model: principals, permissions, ACL grants

Everything reduces to one relation — a grant: principal × permission × dataset, stored as one ACL row (modules/users/models/ACL.py).

  • Principal (Principal.py) is polymorphic: User, Role, and Tenant all inherit from it. Any of the three can hold a grant, which is how role-wide and tenant-wide access work — one ACL row covers every member.
  • Permission (Permission.py) is one of exactly four names, defined in permissions/permission_types.py: read, write, delete, share. share is the meta-permission: it gates granting/revoking access for others.
  • Membership is separate from grants: UserRole and UserTenant link users into roles/tenants. A user's effective access is the union of their own grants and the grants of every role/tenant they belong to.

How grants come into existence

  1. Dataset creation (modules/data/methods/create_authorized_dataset.py): the creating user is granted all four permissions on the new dataset. If the user has a parent_user_id (sub-users/agent identities), the parent is auto-granted all four as well — parents always see their children's datasets.
  2. Explicit sharing (permissions/methods/ authorized_give_permission_on_datasets.py): the caller must hold share on the target datasets, then any principal (user, role, or tenant) can be granted any permission. Revocation mirrors this (authorized_revoke_permission_on_datasets.py).
  3. Capabilities — tenant-scoped grants of actions, not data (landing via PR #4302, currently in review): a new principal_capabilities table, keyed on (principal, tenant, capability). Where an ACL row grants access to a dataset, a capability grants an action inside a tenant — the first one being manage_users. The catalog of capability names is code (CAPABILITY_TYPES in permission_types.py), not a database table, "because the code is what gives each name meaning"; only the assignment of a capability to a principal is data. tenant_id is stored on every row because a user can belong to multiple tenants: it pins each grant to the user's membership in one specific tenant, so holding a capability in one tenant never carries over to the same user's other tenants. Resolution (get_effective_capabilities(user, tenant)) returns the union of what the tenant grants all of its members, what the user's roles in that tenant grant, and what the user was granted personally — there is no deny in the model, resolution is gated on actual tenant membership, and the tenant owner short-circuits as holding every capability. Grant/revoke endpoints ride the permissions router.

Where permissions are enforced

The single chokepoint for dataset resolution is get_authorized_existing_datasets(datasets, permission, user) — every entrypoint resolves names/IDs through it with the permission it needs:

OperationRequired permissionEnforcement path
add / cognify / rememberwritedataset resolution before the pipeline runs
search / recall / visualizereaddataset resolution; retrieval is restricted to documents of readable datasets
delete / prune of a datasetdeletedatasets.py resolves with "delete"
grant/revoke for othersshareauthorized_give/revoke_permission_on_datasets

Two behaviors worth knowing:

  • Denied reads return empty results, not 403. A search against a dataset you cannot read yields [] — deliberate, to avoid leaking which datasets exist. When debugging "search returns nothing", check grants before checking the graph.

Roles, tenants, and who may manage them

  • User management (listing tenant users, assigning/removing roles, adding/removing users) is allowed for the tenant owner always, and today for members of roles named in USER_MANAGEMENT_ALLOWED_ROLE_NAMES (currently {"admin"}, permissions/permission_types.py). That name-matching is a known footgun — any customer group that happens to be called "admin" gets user management — and PR #4302 replaces it: the check becomes "does the requester hold the manage_users capability in this tenant" (owner always passes), with the role-name match kept only as a deprecated fallback so tenants upgrading from the old check don't lose user management until their admin role is granted the capability.
阅读完整来源 ↗