What GenoaCMS stores

GenoaCMS keeps its own state in the default bucket, under a single .genoacms/ prefix. This page describes what appears there, so that an operator inspecting the bucket can tell expected files from unexpected ones.

.genoacms/
├── keys/
│   └── public.json            registry of signing keys
├── security/
│   ├── policy.json            security settings
│   ├── roles.json             what each role may do
│   ├── users.json             who holds which roles
│   ├── sessions/              one record per signed-in session
│   └── rejected/              documents that failed verification
└── components/                component definitions and revisions
text
The default bucket should be private

Everything above is internal state. defaultBucket should have no public read access — see the storage service .

Created at first start

An instance creates all of these the first time it starts, before serving anything. Every one of them is signed, so there is no window in which GenoaCMS reads its own configuration or authorization data without verifying it.

If the bucket is empty after a first run, the instance could not reach it or the secret store — the startup log says which. GenoaCMS still starts in that state, deliberately, so the administrators declared in genoa.config can sign in and repair it. Those declarations are resolved without reading the bucket, which is what makes them a way back in.

The documents

keys/public.json

The registry of signing keys: which key is current, and every key whose signatures still verify. It is signed by the root trust anchor, and it is the one document a consumer SDK fetches — from the root public key it has embedded plus this file, everything else follows.

Superseded keys stay listed, so rotating does not invalidate what earlier keys signed. Revoked keys stay listed too, marked as revoked, so that a revocation is a published fact rather than an absence someone has to notice.

security/policy.json

Security settings an administrator can change at runtime — currently the subordinate key rotation interval. Signed by the root, because it governs the signing keys themselves.

Its initial values come from the security stanza of genoa.config. Editing that stanza afterwards does not change a running instance; this document is the live value.

security/roles.json and security/users.json

What each role may do, and which roles each user holds. Signed by the current subordinate key.

Both are created empty. A new instance therefore grants nobody anything, and the seed administrator — resolved from genoa.config alone, never from these files — signs in to build the first roles.

security/sessions/

One object per signed-in session, named for its family identifier:

.genoacms/security/sessions/8f14e45f-ceea-467a-9b1e-7a12c0e7a1d4.json
text

A record holds the hash of the session's current refresh token, never the token itself, so a copy of this directory does not let anyone sign in as its users. Records are signed like every other document — without that, write access to the bucket would be enough to mint a session.

Signing out deletes the record. So does presenting a refresh token that has already been used, which is treated as a stolen session: the record goes and everyone holding a token for it, legitimate or not, has to sign in again.

Expired records are harmless — the expiry is inside the signed payload, so an expired one grants nothing whether or not anything has got around to deleting it. Deleting the directory signs everyone out; nothing else is lost.

security/rejected/

This directory only exists if something went wrong. When a document fails verification, GenoaCMS copies it here with a timestamp before replacing it, so the evidence survives:

.genoacms/security/rejected/roles-1755950000000.json
text

A file appearing here means the corresponding document could not be verified — because it was edited outside GenoaCMS, corrupted, or signed by a key that has since been revoked. The instance replaces it with an empty signed one and continues, which returns it to seed-administrator-only until roles are rebuilt. The startup log names both paths.

Worth investigating, not deleting

A rejected document is the only record of what was written. Read it before removing it — it is the difference between "storage corrupted a file" and "someone edited our permissions".

After a key rotation

Subordinate keys rotate on an interval, so over time keys/public.json lists more keys than it started with. That is expected. Documents signed by an earlier key keep verifying, because the key remains listed.

Rotating the root is different and is never automatic — see the CLI .