> For the complete documentation index, see [llms.txt](https://docs.makapay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.makapay.io/point-of-sale-pos/security.md).

# Security

## PIN Security

### Storage

Cashier PINs are **never stored in plain text**. The system uses:

* **SHA-256 hashing** with a per-cashier salt
* **32-byte random salt** generated for each cashier (64 hex characters)
* **Timing-safe comparison** to prevent timing attacks during verification

```
Stored: SHA-256(pin + ":" + salt)
```

Even if the database were compromised, PINs cannot be recovered from the hashes.

### PIN Rules

| Rule               | Detail                                  |
| ------------------ | --------------------------------------- |
| Minimum length     | 8 digits                                |
| Allowed characters | Digits only (0-9)                       |
| Uniqueness         | Each cashier must have a unique PIN     |
| Reset              | Only the merchant can reset a PIN       |
| Retrieval          | Not possible -- PINs are one-way hashed |

### Why Unique PINs?

The system identifies cashiers by their PIN during login. When a cashier enters their PIN, the system searches all allowed cashiers for a match. If two cashiers shared the same PIN, the system couldn't tell them apart.

## Session Security

### Token Generation

* **32 bytes** of cryptographically random data (`crypto.getRandomValues()`)
* Stored as a 64-character hex string
* Only the **hash** of the token is stored in the database

### Token Storage

* Primary: **httpOnly secure cookie** (cannot be accessed by JavaScript)
* Backup: **localStorage** (for session recovery if cookie is lost)

### Session Expiration

* Sessions last **15 minutes** from last activity
* Activity (creating payments, navigating) resets the timer
* Expired sessions are automatically cleaned up by a background job

### Session Termination

Sessions are ended when:

* The 15-minute inactivity timer expires
* The cashier manually logs out
* The merchant resets the cashier's PIN
* The merchant deactivates the cashier
* The merchant deactivates the business

## Business Access Control

### Public vs Private Information

| Information                         | Accessible By                                        |
| ----------------------------------- | ---------------------------------------------------- |
| Business Location, code             | Anyone with the business URL (needed for login page) |
| Business settings, allowed cashiers | Merchant only (requires dashboard authentication)    |
| Cashier names (for login display)   | Anyone at the business URL                           |
| Cashier PINs                        | Nobody (hashed)                                      |
| Payment history                     | Merchant only                                        |

### Business URL Security

* Business URLs contain a system-generated ID (`term_<random>`), not the short code
* Business IDs are not easily guessable
* Knowing the URL only gives access to the login screen, not to any payment functions
* A valid PIN is still required to create payments

## Payment Security

* Every payment requires a valid, non-expired session
* Payments are attributed to the authenticated merchant (business owner)
* Order IDs create an audit trail linking payments to businesses and cashiers
* Chain, token, and amount are validated server-side before payment creation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.makapay.io/point-of-sale-pos/security.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
