HandyCafe Docs
cashier

Cashier Login

The Cashier Login screen appears after the required HandyCafe account activation step on a configured server. Every Admin or 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.
  • Forgot admin password? link. Opens the offline Admin password recovery dialog.
  • 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 a username that belongs to a cashier, that cashier account is automatically deactivated. This protects privileged accounts from being brute-forced through client PCs.
  • A deactivated cashier account cannot log in until an administrator reactivates it.
  • Member accounts are never deactivated automatically. Members are protected by the device-level lockout above; failed attempts on a member username do not disable the account.

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"

Cashiers must contact an administrator to reset their password. An Admin can select Forgot admin password? on the staff login screen. Select the Admin username and enter the activated license key. Enter the new password twice and select Reset password. The recovery attempt is locked for 15 minutes after five incorrect license keys.

"My account is deactivated"

A cashier account may have been deactivated by the brute-force protection system (3 failed username attempts) or manually by an administrator. Member accounts are only deactivated manually. Ask your administrator to reactivate the account.

"The login screen does not appear"

The staff login screen appears only after release account activation succeeds. A first-time installation shows the First Setup Wizard after account activation when no local Admin exists.

Next Steps