HandyCafe Docs
cashier

Cashier Login

The Cashier Login screen is the first thing you see when HandyCafe Server starts. Every cashier must authenticate before accessing the dashboard. This page explains the login process, security protections, and what to do if your account is locked.

Login Screen

The login screen appears as a centered card on a clean background with a subtle teal radial glow. It contains:

  • HandyCafe logo. Displayed at the top of the card for brand identification.
  • Application name. "HandyCafe Server" is shown below the logo.
  • Sign-in heading. A localized title and subtitle prompting the cashier to enter their credentials.
  • Username field. A text input with an account icon on the left side.
  • Password field. A password input (masked characters) with a lock icon on the left side.
  • Sign In button. A teal button that submits the credentials.
  • Version number. The current application version is displayed at the bottom of the card.

Logging In

To log in to HandyCafe Server:

  1. Enter your username. Click the username field (it is focused automatically when the screen loads) and type your username.
  2. Press Tab or click the password field. Move to the password field.
  3. Enter your password. Type your password.
  4. Press Enter or click Sign In. Submit your credentials.

Keyboard Navigation

The login form supports full keyboard navigation:

  • Tab moves focus from the username field to the password field.
  • Enter in the username field moves focus to the password field.
  • Enter in the password field submits the form.

Visual Feedback During Login

When the Sign In button is clicked:

  • The form fields reduce to 60% opacity, indicating that a login attempt is in progress.
  • The Sign In button changes to a gray disabled state and cannot be clicked again until the attempt completes.
  • The cursor changes to indicate that interaction is blocked during processing.

Successful Login

After a successful login:

  1. The current cashier is loaded into the application state.
  2. The cashier's role and permissions are retrieved from the server.
  3. The login screen is replaced by the main dashboard.
  4. Sidebar navigation items are filtered based on the cashier's role permissions. Pages the cashier does not have access to are hidden.

Error Handling

If the login attempt fails, an alert dialog appears with the error message. Common error scenarios include:

Error Cause
Username or password empty One or both fields were left blank
Invalid credentials The username or password is incorrect
Account deactivated The account has been disabled by an administrator or by the security system
Device locked Too many failed login attempts from this client triggered a lockout

After an error, the password field is cleared automatically and focus returns to the username field so the cashier can try again.

Error messages are translated into the currently selected language. The system first looks for a localized error code translation. If no translation exists for the specific error code, the raw error string is displayed.

Brute-Force Protection

HandyCafe Server includes built-in brute-force protection to prevent unauthorized access attempts. The protection operates at two levels:

Device-Level Lockout

Failed login attempts are tracked per client device (identified by MAC address):

  • After more than 5 failed attempts from the same device, the device is locked for 3 minutes (180 seconds).
  • During the lockout period, all login attempts from that device are rejected with a "device locked" error, even if the correct credentials are provided.
  • The lockout timer is displayed to the user so they know when they can try again.
  • After the lockout expires, the attempt counter continues from where it left off. The next failure triggers another lockout.

Username-Level Protection

Failed login attempts are also tracked per username:

  • After 3 failed attempts for the same username, the member account associated with that username is automatically deactivated.
  • A deactivated account cannot log in from any device until an administrator reactivates it.
  • This prevents attackers from trying the same username from different PCs.

Security Alerts

When a device lockout is triggered, the server emits a security alert event to the dashboard. This causes:

  • A notification to appear in the server UI alerting the on-duty cashier.
  • An audible beep sound to draw attention.
  • The alert includes the device hostname, the username that was attempted, and the lockout duration.

Audit Logging

Every failed login attempt is recorded in the system logs with:

  • The category "auth" and action "loginRejected"
  • The hostname and IP address of the client device
  • The attempted username and the reason for rejection

This creates a complete audit trail that administrators can review from the Logs page.

Clearing a Lockout

If a legitimate user is locked out, an administrator or authorized cashier can clear the lockout from the Admin Panel:

  1. Find the locked client PC in the Admin Panel (it will show the lockout state).
  2. Use the unlock action to reset the device's failed attempt counter and clear the lockout timer.

The device and username failure counters are also automatically cleared on a successful login.

Admin vs. Cashier Accounts

There are two types of accounts that can log in to HandyCafe Server:

Admin Account

  • Created during the First Setup Wizard when HandyCafe Server is installed for the first time.
  • Has unrestricted access to all pages and features.
  • Can create, modify, and delete other cashier accounts.
  • Can configure system settings, pricing, and all other administrative functions.

Cashier Accounts

  • Created by an administrator from the Management section of Settings.
  • Assigned a role that defines which pages they can access and which actions they can perform.
  • Cannot access pages or features that their role does not permit.
  • See Cashier Roles and Permissions for details on configuring roles.

Troubleshooting

"I forgot my password"

HandyCafe does not have a self-service password reset. Contact your administrator to reset your password from the Management settings.

"My account is deactivated"

Your account may have been deactivated by the brute-force protection system (3 failed username attempts) or manually by an administrator. Ask your administrator to reactivate your account.

"The login screen does not appear"

If the application opens directly to the dashboard without showing a login screen, it means a cashier session is already active. To switch users, log out from the current session first.

Next Steps