Access and identity
Core proves who is calling and loads what they may do; each route says what it needs; each plugin decides who may see a particular record.
Signing in
Section titled “Signing in”- Email and password, with a lockout guard; the same answer (“Invalid email or password”) for every failure, so accounts cannot be discovered.
- SSO (OpenID Connect) per instance: code flow with PKCE, ID token validation, account linking by
verified email. Administrators configure providers in App Admin (
identity:configure) and may turn local sign-in off. - Authenticator apps (TOTP) are required for
adminandsuperadmin: sign-in is two steps. - Activation links (first admin, invitations) are single-use; the code travels in the URL fragment and only its hash is stored.
Sessions
Section titled “Sessions”Every sign-in is a row in sessions. The access token is short-lived and carries only the user id
and the session id; every request checks the session and reloads current roles and permissions,
so a revoked session or a removed role takes effect at once. Refresh tokens are opaque, rotate on
each use, and a reused one revokes its session. People see and end their sessions; administrators
can sign someone out everywhere. Durations are required settings (SESSION_ACCESS_TTL_SECONDS,
SESSION_IDLE_TTL_SECONDS, SESSION_ABSOLUTE_TTL_SECONDS).
In the browser, tabs share one session: one refresh at a time across tabs, and signing out in one tab signs out the others.
Roles and permissions
Section titled “Roles and permissions”Permissions decide, never role names. Roles are each organisation’s own; administrators grant permissions to roles in App Admin.
| Role | Has |
|---|---|
user |
The user app; plugins grant their own permissions to it by default (chat:read, sales:write, …) |
admin |
App Admin (admin-app:access), core administration permissions, managers’ plugin permissions (sales:manage) |
superadmin |
Every permission. Created once per instance |
Guardrails: system roles stay; the last superadmin stays; someone always holds roles:write.
Per route, then per record
Section titled “Per route, then per record”- Per route. Global guards run in order: rate limit → token and session → roles → permissions.
A plugin route must carry
@Permissions(...)with permissions declared in its manifest, or a deliberate@Public(); core refuses to start otherwise. - Per record. Whether you may see this lead depends on the lead, so the plugin decides in its service, on every call. Someone who may not see a record gets “not found”, not “forbidden” — no hint that it exists.
Example — Sales: you see your own leads, leads where you are in a meeting or own a follow-up, and
managers (sales:manage) see all. The rule is one SQL condition used by every query.
Public routes
Section titled “Public routes”@Public() routes skip sign-in and must protect themselves: the Sales website form answers only
while the setting is on, rate-limits per address and has spam traps; avatar links answer only for a
person’s current photo.