Permissions
Source permissions are allow-only. There are no deny rules, so evaluation is one question — does any grant allow this? — with no precedence order to reason about. What an agent may do is exactly the union of the grants it holds.
Grants#
A grant names four things:
- subject — a principal (human or agent), an org, or
public. - libraryId — the library it applies to.
- pathPrefix —
/for the whole library,/runbooksfor a subtree, or""(unscoped, see below). - actions — the fine-grained verbs allowed, such as
read,write,create_folder,delete,comment,manage_grants,view_audit.
A request is allowed when any grant matches: the subject is you, one of your orgs, or public, and the grant's path prefix is a prefix of the target path. Prefixes match on path segments — a grant on /a/b covers /a/b/c.md, not /a/bc.md.
Roles#
Roles are macros that pack actions. They expand at grant time and the grant stores the expanded set, so redefining a role never silently changes permissions issued earlier.
| Role | Actions | In short |
|---|---|---|
| reader | read, comment |
Read documents and comment on them. |
| writer | read, comment, write, create_folder |
Everything a reader can, plus write files and create folders. |
| admin | read, write, create_folder, delete, comment, share, manage_grants, manage_principals, create_library, view_audit, view_stats, manage_billing, manage_org |
Every action on the scope, including grants, sharing, and audit. |
The unscoped writer#
A writer grant with an empty path prefix ("") means: write inside folders you created. This is the default shape for a new agent — it can build out its own corner of a library without being able to touch anyone else's.
Two bootstrap rules make it work from an empty library: creating a top-level folder counts as within-own-scope, and a node counts as yours while you are the one creating it. From there, everything the agent creates under its own folders is writable by construction.
Owners#
The principal that owns a library holds an implicit admin grant on / — no grant document required, nothing to revoke by accident.
No existence leak#
Denied reads return not_found, never permission_denied — on REST, MCP, and the web viewer alike. An unauthorized caller cannot learn whether a path exists. Listing operations show you only the nodes you can read.
Sharing and orgs#
Sharing documents and folders with specific accounts, orgs, or the public — and org-owned libraries with membership management — is coming next; grants are already the substrate it builds on. Public shares will render as logged-out viewer pages.
Audit#
Every mutation and auth event appends to the audit log. Reading it is itself permission-gated behind the view_audit action — admins hold it, readers and writers do not. Deletes are soft everywhere, so the log always has something to point at.