Users

The Users page manages authentication and authorization for the Chompy platform. Chompy uses a role-based access control (RBAC) system with JWT token authentication. Every user is assigned a role that determines what they can view and modify across the application.

Roles

Chompy supports two user roles:

Role	Badge Color	Permissions
Admin	Purple	Full access to all features. Can view all dashboards and data, modify settings and configuration, manage devices and sites, create and delete users, manage credentials, deploy probes, and execute configuration changes.
Viewer	Gray	Read-only access. Can view all dashboards, flow data, alerts, topology maps, and reports. Cannot modify settings, manage devices, change credentials, or perform any write operations. Viewer users see configuration pages but action buttons (save, delete, add) are hidden or disabled.

Admin users are identified by the purple admin badge next to their name. The currently logged-in user is additionally marked with a blue You badge.

User Management

The User Management list displays all registered accounts as cards showing:

• Full Name — The user's display name shown throughout the UI.
• Role Badge — admin (purple) or viewer (gray).
• Email — The user's email address, used for login.
• Last Login — Timestamp of the user's most recent successful authentication.

+ Add User

Opens a form to create a new user account. Required fields:

• Username — A unique login identifier. Cannot contain spaces. This is the primary credential used for authentication.
• Email — Must be unique across all users.
• Full Name — Display name shown in the UI and audit logs.
• Password — The initial password for the account. Passwords are hashed with bcrypt before storage — the plaintext password is never persisted. Communicate the initial password to the user securely and encourage them to use a strong password.
• Role — Select Admin (Full Access) or Viewer (Read Only).

Edit User

Click the edit (pencil) icon on a user card to open the Edit User modal. Editable fields include:

• Username — Can be changed, but must remain unique.
• Email — Can be changed, but must remain unique.
• Full Name — Display name.
• Role — Switch between Admin and Viewer. Changing a user's role takes effect on their next login or token refresh.
• Active — The active checkbox controls whether the user can log in. Unchecking this effectively disables the account without deleting it. Disabled users cannot authenticate and existing sessions are invalidated.

Click Update User to save changes, or Cancel to discard.

Reset Password

The Reset Password button at the bottom of the Edit User modal generates a new temporary password or allows the admin to set a new password for the user. This is useful when a user has forgotten their password. The new password is hashed with bcrypt before storage.

Delete User

Click the delete (trash) icon to permanently remove a user account. This deletes the user record and all associated sessions from PostgreSQL. Audit log entries referencing the deleted user are preserved (with the user_id set to null) for security traceability. You cannot delete your own account.

Authentication

Chompy uses JWT (JSON Web Token) authentication. When a user logs in with their username and password, the backend validates the credentials against the bcrypt-hashed password in PostgreSQL and issues a signed JWT token. The token is included in all subsequent API requests via an HTTP-only cookie.

Key authentication behaviors:

• Token Expiry — JWT tokens expire after the configured duration (default 24 hours). Users are redirected to the login page when their token expires.
• Session Tracking — Active sessions are tracked in the sessions table with token hash, IP address, user agent, and last activity timestamp.
• Login Attempts — Failed login attempts are recorded in the audit log with the IP address and timestamp for security monitoring.
• Route Protection — All API routes under /api require a valid JWT token, with the exception of /api/auth/login and certain internal service endpoints (e.g., synthetic alert ingestion from the Go probe service).

Access Control

The backend enforces role-based access using middleware functions applied to each API route:

• authenticateToken — Validates the JWT token on every request. Returns 401 if the token is missing, expired, or invalid.
• requireAdmin — Blocks the request with 403 if the authenticated user's role is not admin. Applied to all write operations (create, update, delete) across settings, devices, sites, users, and integrations.
• requireWriteAccess — Verifies the user has permission to modify resources. Currently maps to admin role but designed to support additional roles in the future.

Viewer users can access all GET endpoints (dashboards, flow queries, device lists, alert history) but are blocked from POST, PUT, and DELETE operations on configuration resources.

Audit Logging

All significant user actions are recorded in the audit_log table, including user creation, deletion, role changes, credential modifications, configuration changes, device management, and probe deployments. Each audit entry includes the user ID, username, action type, affected resource, IP address, user agent, and timestamp. Audit logs can be reviewed for security investigations and compliance purposes.

Default Accounts

A fresh Chompy installation includes two default user accounts:

Username	Role	Default Password
admin	Admin	admin123
viewer	Viewer	viewer123

Change Default Passwords

Change the default passwords immediately after your first login. Default credentials are publicly documented and must not be used in production environments.

Future Authentication

The authentication system is designed with extensibility in mind. The current username/password authentication will be augmented with additional identity providers in future releases, including LDAP/Active Directory integration and OAuth/SSO support. The existing role model and JWT session management will serve as the foundation for these integrations.