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.

PermissionScope
storage:bucket:reada bucket
storage:bucket:writea bucket
storage:bucket:deletea bucket
db:collection:reada collection
db:collection:writea collection
db:collection:deletea collection
components:readinstance
components:registerinstance
components:modifyinstance
components:codeinstance
pages:readinstance
pages:content_editinstance
pages:structure_editinstance
pages:publishinstance
pages:deleteinstance
config:users:manageinstance
config:roles:manageinstance
config:keys:manageinstance
config:security:manageinstance
config:adapters:manageinstance

A few are worth reading twice:

  • pages:content_edit and pages:structure_edit are 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:delete is 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:code is simply a capability only a component authored here has any use for.
  • Removing a component needs components:register, not modify. Removal is the inverse of registration, so a role meant to adjust a component's attributes cannot destroy one that pages depend on.
  • components:register is about a component's existence, not its source. Creating and deleting need it; reading, editing and publishing the code do not.
  • components:code covers 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 grant config:roles:manage.
  • config:keys:manage covers 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 its read and write grants, described below — not by a separate permission.
config:roles:manage is full authority

Whoever 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: '*' }
ts

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'] }
ts

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_price cannot 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']
  }
}
ts

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.

AI agents hold roles too

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 .

This is also the way back in

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:read and db: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.
Who can see the list of buckets and collections

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:

SituationResult
A user holds no rolesSigned in, denied everything
A role names a permission that no longer existsThat grant matches nothing; the rest of the role still applies
A user names a role that no longer existsThat role contributes nothing; the rest still apply
roles.json or users.json fails verificationQuarantined and replaced with an empty one; only declared administrators can act
The bucket is unreachableNo 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.