Documentation
¶
Overview ¶
Package tokenperm is the catalogue of an API key's permissions that come in LEVELS: what a key may do with one kind of thing beside its files - read it, or read and write it. The first one is `comments` (task #157).
A key's list (model.APIToken.Scopes) holds three kinds of entries:
- the verbs `read`, `write`, `delete`, `mcp`, `admin` (auth/drivers/apitoken);
- at most one `root:<storage>://<path>` confinement (package confine);
- a permission at a level, `<key>:<level>` - `comments:rw`.
Every permission states its default (the maintainer, 2026-10-06) ¶
A key whose list does not name a permission holds that permission's DefaultLevel. That is how every key minted before a permission existed gets it, and how a new key gets it when whoever minted it chose nothing - with no migration and no rewrite of stored rows. The rule for the default:
- every permission defaults to Read;
- a super-administrator kind of permission (administration, tenants, server settings) defaults to None: it is never handed to a key that did not ask for it. Superadmin marks one.
"bundan sonra eklenecek tüm permissionlar default read olarak konulur, superadmin tarzı yetkiler sistemde yoksa" - the maintainer's words. Each catalogue entry says its default explicitly, and tokenperm_test.go fails for an entry that does not, for a default that breaks the rule, and for a shipped default that changed (a changed default silently changes every key that never named the permission). docs/RBAC.md → "Permissions with a level" and docs/CONTRIBUTING.md → "Adding a permission" say it for people.
⚠ This package imports nothing of filex's own: the model, the auth chain and the token issuer all read it, and it must not pull any of them in.
Index ¶
Constants ¶
const Comments = "comments"
Comments is reading a file's or a folder's comments (Read) and adding and deleting them (ReadWrite) - on /api/files/comments, /api/ai/comments and the MCP file_comment_* tools alike (auth.CommentsRead, auth.CommentsWrite).
Variables ¶
This section is empty.
Functions ¶
func Canonical ¶
Canonical is the entries a list stores for levels: one `<key>:<level>` per permission whose level is not its default, in catalogue order. A permission at its default is not written - it reads the same, and a key minted before the permission existed then looks exactly like one minted after it.
func LevelsIn ¶
LevelsIn is LevelIn for every permission of the catalogue: what the token lists answer beside `scopes` (`"permissions": {"comments": "read"}`), so a screen draws a key's levels without a copy of the default rule.
func Replace ¶
Replace returns scopes with the levels of changes set: every other entry - the verbs, the `root:` - stays where it was, the permissions changes does not name keep their level, and the permission entries are written again in their canonical form at the end. An entry this version cannot read is dropped with them (Replace writes what it can read back).
Types ¶
type Def ¶
type Def struct {
// Key names the permission in a key's list (`comments` → `comments:rw`)
// and in the answers that list a key's levels.
Key string
// Levels are the levels a key may be given, lowest first.
Levels []Level
// DefaultLevel is the level of every key whose list does not name the
// permission - the keys that existed before it was added among them.
// ⚠ Required, and fixed once shipped: Read, or None for a Superadmin
// permission (the package comment; tokenperm_test.go).
DefaultLevel Level
// Superadmin marks a permission that amounts to administering the server
// or a tenant. It defaults to None.
Superadmin bool
}
Def is one permission of the catalogue.
type Level ¶
type Level string
Level is how far a key may go with one permission.
const ( // None: not at all. Only a super-administrator kind of permission // defaults to it. None Level = "none" // Read: see it. Read Level = "read" // ReadWrite: see it, add to it and remove what one may remove. Written // `rw` in a key's list; `write` is read as the same level. ReadWrite Level = "rw" )
func LevelIn ¶
LevelIn is the level a stored list gives the permission key: the level it names, else the permission's default.
⚠ An EMPTY list grants nothing (model.APIToken.HasScope), so it holds every permission at None, and so does a key the catalogue does not know. An entry this version cannot read - a level the permission does not have, say one a later version added - is passed over and the default holds.
func ParseEntry ¶
ParseEntry reads one entry of a key's list. isPerm is false for an entry that is not a permission of this catalogue (a verb, a `root:`, anything else - the caller judges those); err is a *LevelError for an entry that names a permission with a level it does not have.
func ParseLevel ¶
ParseLevel reads a level as a request or a stored list spells it. `write` is the same level as `rw`: a refusal says `comments:write`, and a client that adds exactly what the refusal named gets what it asked for.
type LevelError ¶
LevelError is a permission entry with a level its permission does not have.
func (*LevelError) Error ¶
func (e *LevelError) Error() string
Source Files