Roles and permissions
GenoaCMS decides what a signed-in user may do from roles. A role is a named set of grants; a user holds roles; a grant names a permission and the resource it applies to.
Authorization is not a service: there is no provider to register and no adapter behind it. It is a core module of GenoaCMS, and its data lives in your own bucket. Only who your users are is delegated — to the authentication service , because "who are you?" is a standardized question in a way that "what may you do here?" is not.
Permissions
Twenty-three, in four domains. Permission names are fixed: you compose roles from them, you cannot invent one.
| Permission | Scope |
|---|---|
storage:bucket:read | a bucket |
storage:bucket:write | a bucket |
storage:bucket:delete | a bucket |
db:collection:read | a collection |
db:collection:write | a collection |
db:collection:delete | a collection |
components:read | instance |
components:register | instance |
components:modify | instance |
components:code | instance |
pages:read | instance |
pages:content_edit | instance |
pages:structure_edit | instance |
pages:publish | instance |
pages:delete | instance |
config:users:manage | instance |
config:roles:manage | instance |
config:keys:manage | instance |
config:security:manage | instance |
config:adapters:manage | instance |
A few are worth reading twice:
pages:content_editandpages:structure_editare different jobs. Editing the text in a component is content; adding, removing or rearranging components is structure. A copywriter needs the first and not the second.- A move is a write, not a delete. Renaming or relocating an object needs
storage:bucket:write.storage:bucket:deleteis only for destroying things. - The four component permissions do not distinguish the two kinds of component. A component
whose code lives in your application and one written in the CMS are described the same way and
listed in the same catalog, so the line the permissions draw is between describing a component
and writing its code — not between the kinds.
components:codeis simply a capability only a component authored here has any use for. - Removing a component needs
components:register, notmodify. Removal is the inverse of registration, so a role meant to adjust a component's attributes cannot destroy one that pages depend on. components:registeris about a component's existence, not its source. Creating and deleting need it; reading, editing and publishing the code do not.components:codecovers reading source, writing it and publishing it. These are deliberately one permission and not three: anything that can read a component's source can also publish an executable built from it. A reviewer who may read but not write, or a publisher who may release what others wrote without altering it first, cannot be expressed. Publishing runs static analysis, compiles, signs with the key hierarchy and produces code your visitors execute — so grant this as narrowly as you grantconfig:roles:manage.config:keys:managecovers reading the key registry as well as changing it. There is no separate read permission: the registry is published for consumers to fetch, so there would be nothing to withhold. See signing keys .- There is no
db:collection:schema. Restricting a role to part of a collection is done by naming fields on itsreadandwritegrants, described below — not by a separate permission.
config:roles:manage is full authorityWhoever can administer roles can create a role holding every permission and assign it to themselves.
No barrier against that is attempted, because a partial one would be worse than an honest statement:
grant this permission as narrowly as you would grant components:code.
Scopes
Instance-scoped permissions apply everywhere. Bucket- and collection-scoped permissions name which one:
// read the media bucket, and only that one
{ permission: 'storage:bucket:read', resource: { scope: 'bucket', id: 'media' } }
// read every collection
{ permission: 'db:collection:read', resource: '*' } The scope is part of the match, not decoration: a grant on the media bucket does not match a media collection.
Fields
db:collection:read and db:collection:write can name which fields of a collection they cover.
The two are named separately, which is how "may see the price but not change it" is written:
// may read the price, may only change the name
{ permission: 'db:collection:read', resource: { scope: 'collection', id: 'products' },
fields: ['name', 'price'] },
{ permission: 'db:collection:write', resource: { scope: 'collection', id: 'products' },
fields: ['name'] } A grant with no fields covers every field, including fields added to the collection later. A
grant that names fields covers exactly those, so a field added later is not included — a restriction
stays as narrow as you wrote it when the schema grows.
Deleting a document does not address fields, so db:collection:delete takes no field list.
Two things follow from that, and both are worth knowing before you restrict a role:
- A field added to the collection later is not covered by a grant that names fields. Restrict a role and you are restricting it to the fields that existed when you wrote the grant.
- Omitting a field never erases it. Writes merge against the stored record, so a user who cannot
write
wholesale_pricecannot clear it by saving a document without it. Only the fields they may write are taken from what they submit.
Declaring roles in genoa.config
Roles and assignments declared in configuration are authoritative. A new instance needs at least one assignment, or nobody can administer it:
authorization: {
roles: {
Administrator: [{ permission: '*', resource: '*' }],
Copywriter: [
{ permission: 'pages:read', resource: '*' },
{ permission: 'pages:content_edit', resource: '*' }
]
},
assignments: {
'a1b2c3d4-...': ['Administrator']
}
} The key in assignments is the subject — the provider-issued identifier your authentication
provider returns, never an email address. Email addresses change hands; a subject is the stable
identity a permission decision can rest on.
What configuration declares cannot be changed from inside the CMS:
- Editing or deleting a declared role or assignment is refused, not quietly undone later.
- Deleting a declaration removes it from the instance, and revokes the access it granted. It does not leave an editable copy behind.
- Runtime administration is still free to create roles and assignments configuration does not name.
Set authorization.lockRoles to true to disable runtime administration altogether.
An AI agent is an account of its own, typed apart from people, and holds roles through the same assignments under a subject agent:<name>. It can never hold a config:* permission or *. See AI agents .
Declarations are resolved without reading the bucket. If your authorization documents are
missing, or fail their signature check, the administrators named in genoa.config can still sign in
and repair the instance — and nobody else can.
Administering roles from the CMS
Configuration → Roles and access lists every role and account, declared ones included. Declared entries appear marked as read-only rather than hidden, so you can see where a subject's authority comes from even though you cannot change it here.
A grant is composed as two choices. First the permission, picked by category — storage, database, content, configuration. Then, if the permission is bucket- or collection-scoped, which buckets or collections, switched on from the ones this instance actually has:
- The list is the instance's own catalog, so a grant cannot name something that does not exist. A mistyped name would otherwise produce a grant that looks granted and denies every request.
- One row can cover several resources. "May read these three buckets" is one row; it is saved as one grant per bucket.
- "Any bucket" and "any collection" are available, and are not the default. They are the widest grant you can write, so they are worth choosing on purpose.
- For
db:collection:readanddb:collection:write, each selected collection gets its own field switches — see Fields above. "Every field" is a switch of its own, because it means something a list of all the current fields does not: it covers fields added later.
Anyone holding config:roles:manage — the names only, no contents and no credentials. That
permission is already full authority, as noted above, so hiding the names from its holder would
protect nothing.
Newly created collections appear after a restart: the collection list is read once when the instance starts.
What happens when something is wrong
GenoaCMS fails closed. Every one of these grants nothing:
| Situation | Result |
|---|---|
| A user holds no roles | Signed in, denied everything |
| A role names a permission that no longer exists | That grant matches nothing; the rest of the role still applies |
| A user names a role that no longer exists | That role contributes nothing; the rest still apply |
roles.json or users.json fails verification | Quarantined and replaced with an empty one; only declared administrators can act |
| The bucket is unreachable | No stored authority resolves; only declared administrators can act |
There is no setting that relaxes this, and no state in which an unreadable manifest results in more access rather than less.
A rejected document is copied to .genoacms/security/rejected/ before being replaced — see what GenoaCMS stores . Read it before deleting it: it is the difference
between a corrupted file and someone editing your permissions.
Where enforcement happens
Every permission is checked in the service layer, next to the operation it protects — not in the page that calls it. Hiding a button is presentation; the denial underneath it is the control. An interface that forgets to hide something is untidy, not insecure.
Grants are resolved per request and cached briefly, so removing a role takes effect within grantCacheSeconds rather than when the user's session ends.