Disimula – A Party Game of Secret Missions

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.

Request path and authentication

There are three other kinds of caller, each with its own credential:

CallerCredentialMay call
AI workerAuthorization: Bearer <WORKER_TOKEN>, compared in constant timeonly its queue endpoints
PaddleHMAC signature of the webhook body, from Paddle's IPs onlyonly the webhook endpoint
Dev modenone: every request is AUTH_DEV_EMAIL, or the user in X-Dev-Usereverything, 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):

PermissionGrants
games.organizecreate and run games
missions.catalogsee and deal the themes everybody sees
missions.privateprivate mission sets, by hand or with AI
billing.purchasebuy, and see one's own payments
missions.generategenerate catalog variants with AI and review them
users.read, users.writemanage users and sign-up
users.impersonateborrow another user's role
credits.grantgive AI credits
roles.read, roles.writemanage roles
stats.readthe admin panels
plans.writetiers, 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_EMAIL only 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 UserDeleted event 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.