Disimula – Users and roles
Cloudflare Access for identity, the app for authorization - roles made of fine-grained permissions, self sign-up bounded by free-plan seats, impersonation and soft deletion.
Identity: Cloudflare Access
The app has no passwords. Cloudflare Access stands in front of organiza.disimula.app and
handles sign-in (one-time PIN by email, or any identity provider configured in Zero Trust). Every
request that reaches the backend carries a signed JWT in Cf-Access-Jwt-Assertion, forwarded by the
Next.js proxy, and the backend verifies it:
- signature against the team's public keys (
<team>.cloudflareaccess.com/cdn-cgi/access/certs); - issuer is the team domain, the token is not expired;
- audience contains the application's AUD tag, so a token minted for another Access application in the same account is rejected.
Its email must belong to an active user of the app. Getting past Cloudflare is not enough: someone whose email is not a user can only see whether sign-up is open, and sign up.
There are three other kinds of caller, each with its own credential:
| Caller | Credential | May call |
|---|---|---|
| AI worker | Authorization: Bearer <WORKER_TOKEN>, compared in constant time | only its queue endpoints |
| Paddle | HMAC signature of the webhook body, from Paddle's IPs only | only the webhook endpoint |
| Dev mode | none: every request is AUTH_DEV_EMAIL, or the user in X-Dev-User | everything, to try roles locally |
There is no default auth mode: without AUTH_MODE the backend refuses to start, and dev refuses
to start if Cloudflare settings are present, so a production box cannot silently come up without
sign-in.
Authorization: roles and permissions
Each user has one role; a role is a set of permissions (shared/domain/Permission):
| Permission | Grants |
|---|---|
games.organize | create and run games |
missions.catalog | see and deal the themes everybody sees |
missions.private | private mission sets, by hand or with AI |
billing.purchase | buy, and see one's own payments |
missions.generate | generate catalog variants with AI and review them |
users.read, users.write | manage users and sign-up |
users.impersonate | borrow another user's role |
credits.grant | give AI credits |
roles.read, roles.write | manage roles |
stats.read | the admin panels |
plans.write | tiers, limits, passes, subscriptions, promo codes |
- The built-in admin role grants everything; a starting Organizador role grants the first four.
- Every endpoint states its permission with
@PreAuthorize, enforced by an ArchUnit test. - No privilege escalation: managing users or roles can never grant more than the caller has
(
403 role_escalation), the registration role can never be admin, and the last admin cannot be removed or lock themselves out. - Ownership beats roles. Games and private sets belong to their owner: their endpoints answer 404 to anyone else, admins included. Admins see them only through read-only panels, as names, counts and dates: never a game's decks or a private set's missions.
ADMIN_EMAILonly bootstraps the first admin: it is made one at start while the database has no active admin. Once admins exist, the app decides who they are, so demoting or deactivating that email sticks across restarts (an inbox that gets compromised can be locked out). Since the last admin can never be removed, there is always one.
The UI hides what a role cannot do (components/access.tsx), but only for clarity: the backend
checks every call.
Impersonation
Admins with users.impersonate can borrow another user's role to see the app as they do, for
support. They never borrow the user's data: their games stay their own. And it can never raise
privileges: only roles that grant nothing the impersonator's own role does not can be borrowed, and
that is checked again on every request, so changing either role ends it.
Self sign-up, bounded by free seats
People can create their own account: after signing in with Cloudflare, the sign-up page asks for a name and acceptance of the terms; the backend stores which version of the terms was accepted and when. Admins control sign-up from the app:
- Open or closed (closed when first deployed).
- Maximum users, counting every account that is not deleted. When reached, sign-up closes by itself and stays closed until an admin reopens it.
- Role given on sign-up.
The maximum can never exceed REGISTRATION_SEAT_LIMIT (50), because Cloudflare Zero Trust's free
plan allows 50 seats, and anyone who passes the Access login takes one, even if they never sign up.
Seat expiration in Zero Trust gives back the seats of people who stop coming.
Deleting an account
Deleting is soft, whether by the user ("My account") or by an admin. The row stays with its id and dates, for what may refer to it later (payments, for instance), but:
- the email becomes
deleted-<id>@deleted.invalid, the name and role are cleared; - a
UserDeletedevent has each feature delete what the user owned: games, online rooms, private sets, pending generations; - the same email can sign up again later, as a new account.
Players need no account
Players never sign in: they get printed cards, or join an online room by its code on a page that is not served from the home server. Only organizers and admins have accounts.