Access control

Access control in Truke KF is based on labels — short text tags assigned to both users and items.

Labels

A label is a plain text tag, for example staff, beta, or finance. Labels are case-sensitive.

A user holds a set of labels. An item's ACL is a list of labels, each of which can carry the operations it grants after a colon:

Each operation is granted only by its own letter: finance:w lets a user edit an item, but not read or delete it. To edit an item a user will usually need rw.

Rules

An empty ACL, on either side, means that no rules apply:

• An item with no labels is open: everyone can read, write, add children to and delete it.
• A user with no labels has every right, on every item.

Otherwise:

• A user may perform an operation on an item if they hold a label that the item's ACL grants that operation to. * in an item's ACL stands for any user.
• A user holding the label or admin has every right, on every item. On a user, stands for every right; on an item, for every user.
• A request with no logged-in user is anonymous, and may only use items with no labels.

Leaving a user's labels empty is a deliberate grant of every right. Users created automatically at their first single sign-on are never left empty: they receive the configured default labels (staff unless set otherwise).

Subitems

An item's parent is the item that holds it as a component (∋), a task (*) or a sidebar link (-). Labels follow that parent:

• A new item takes its parent's labels. The add form shows them, already filled in. Items linked any other way, such as an event caused by an item, start with no labels.
• A change reaches the items that followed. When an item's labels change, every item below it that still had the old labels gets the new ones. An item given labels of its own keeps them, and so does everything below it that follows those.
• A moved item that followed its old parent takes the new parent's labels. One with labels of its own keeps them.

Items tagged reference, which are shared between several parents, are left out of all three: they keep the labels they are given.

Who may change labels

Setting an item's labels takes every right on it — a label carrying rwad, or

* / admin on the user. The same goes for creating an item with labels other than the ones it would take from its parent: it takes every right on the parent. Anyone may restrict an item that has no labels, because on such an item everyone has every right. Without that right the field is shown but cannot be edited.

The same rules on every surface

Access control is not a property of the web interface. The browser, the REST API and the MCP endpoint are checked in one place, against the same labels, so a token cannot reach anything its owner could not reach by clicking.

Two consequences are worth stating plainly, because they change what an integration sees:

An unauthorized read is answered as 404, not 403. Confirming that an item exists but is off limits is itself a disclosure — it tells the caller there is something there, and often what it is called. Writes answer 403, since by then the caller has already shown they know what they are aiming at.

Lists are filtered, and their totals are counted afterwards. Search results, items by tag, relations, checklist rows and the failure-analysis walk all drop what the caller may not see, and the reported total reflects that. What you get back is what you may see, not a truncated view of what exists.

Example

• Item A: Alice can read, edit and delete it. Bob cannot see it.
• Item B: Both Alice and Bob can see it. Neither can edit it.
• Item C: Both can see it; only Alice can edit it.
• Item D: Everyone can see it and edit it.
• Carol has no labels, and so can do anything with all four items.