Users and roles

Sign in at /login with email and password. If the account has 2FA enabled, a TOTP code or recovery code is required. Success sets an HMAC-SHA256 cookie jf_session (14-day TTL). POST /api/auth/login is rate-limited (20 / IP / 15 min and 10 / email / 15 min) and skips CSRF. POST /api/auth/logout ends the session (and increments token_version, so every device is signed out). Actions: auth.login, auth.logout, auth.loginFailed.

Roles#

Stable capability names live in @justflows/sdk (USER_CAPABILITIES, ROLE_CAPABILITIES, roleHasCapability). Check capabilities in extension code; many Express routes still gate on role names (requireRole).

User admin#

Admin → Users lists real accounts from GET /api/users (administrator or editor). Administrators can invite a user (POST /api/users/invite) — the account is created with a role and a temporary password is emailed — and open a dedicated Edit user page (/admin/users/:id) to change display name and role, reset the account's password, or remove the user. POST / PATCH / DELETE /api/users are administrator-only and refuse any change that would leave the site with zero administrators. CLI: justflows user create.

Custom roles#

Beyond the five built-in roles, an administrator can define site-local custom roles with a capability editor (Admin → Users). Built-in defaults are safe, assignment is guarded, and every change is an audit event. Only capabilities from active plugins appear in the editor — commerce and other extension-owned domains are contributed at runtime, not hard-coded. SDK: AccessPolicy, AccessScope, effective capability and scope helpers, access-change hooks, and ctx.capabilities.register().

Per-user grants and scopes#

A specific user can be given extra capabilities, or explicit denies, on top of their role. Grants can be scoped — by content type, locale, site, and ownership — and the editor shows a human-readable preview of the resulting effective access. Changing a user's policy revokes their existing sessions, and you cannot apply a policy change to your own account.

Sessions and devices#

Account Security lists your database-backed device sessions and marks the current one. Revoke a single session or every other session; an ordinary logout now ends only the current device. This is the first slice of the wider identity roadmap — OIDC/OAuth, SAML, and administrator MFA policy are still to come.

Self-service password reset#

A Forgot password? link on the sign-in and registration screens emails a single-use, time-limited link (JF_PASSWORD_RESET_TTL_MINUTES, default 60) that lets a user set a new password without shell or database access. Tokens are stored only as SHA-256 hashes, bound to one account, and invalidated on use, on any password change, and on expiry. The response is identical whether or not the address exists, and both the request and the redemption are rate limited per address and per IP. A completed reset revokes every session. Administrators can disable the flow or restrict it to chosen roles under Admin → Settings; when outgoing mail is unconfigured, justflows user reset-password --email you@example.com is the fallback. New password_resets table (migration 0017).

Passwords and two-factor authentication#

Passwords are PBKDF2-SHA256, 310,000 iterations, stored as $pbkdf2$…. Minimum length is 12. Admin → Security → Your account can change your password; an administrator can reset another account. Both bump token_version and revoke every session.

TOTP (RFC 6238) is optional per user. Enrolment is POST /api/auth/2fa/setup then POST /api/auth/2fa/enable with a valid code. Secrets and single-use recovery codes are encrypted at rest (migration 0007_totp). Disable with POST /api/auth/2fa/disable. Federated login (OIDC/SAML) is not in this release; device-session revocation is available (see Sessions and devices above).

Personal data#

GET /api/users/:id/personal-data returns data held about that account. POST /api/users/:id/erase anonymises their comments, deletes their form submissions, and strips IP and user agent from their audit entries. Content they authored is reassigned, not deleted.