![](./src/static/images/logo.svg)

# Lagomare Gates

A web-based gate access management and control system. Authorized users can remotely open physical gates via a mobile-friendly PWA. An admin dashboard provides full management of gates, access codes, and users.

## Features

- **Keypass authentication** — users authenticate with an access code; each keypass can have a per-gate allowlist, an optional expiration date, and an optional time/day-of-week schedule
- **Keypass schedules** — restrict a keypass to specific days of the week and/or a time window (e.g. Monday–Friday 08:00–18:00, server local time)
- **Remote gate control** — integrates with [AVConnect](https://www.avconnect.it) and [Shelly Cloud](https://shelly.cloud) to trigger gate macros/relays
- **Gate icons** — each gate can be assigned any UTF-8 character or emoji as its icon, displayed on the user app button and keypass selector
- **Role-based admin panel** — two roles (`admin`, `manager`) with different permission levels
- **Two-factor authentication (TOTP)** — admins can enable app-based 2FA (Google Authenticator, Authy, etc.) on their account
- **Access audit log** — every open attempt is logged with timestamp, keypass, gate, IP, and result; filterable and paginated
- **Keypass QR codes** — generate a scannable QR code for each keypass; scanning opens the PWA and logs in automatically
- **Keypass code options** — choose character set (alphanumeric, alpha, numeric, or a 4-word passphrase) and length when auto-generating codes
- **Telegram notifications** — optional push notifications to a Telegram group whenever a gate is opened
- **Progressive Web App** — installable on mobile devices with offline caching

## Tech Stack

| Layer | Technology |
|---|---|
| Backend | FastAPI + Uvicorn |
| ORM | SQLAlchemy |
| Database | SQLite |
| Auth | JWT (HS256) + bcrypt |
| 2FA | TOTP (RFC 6238) via pyotp |
| Credential storage | Fernet symmetric encryption |
| Gate integration | AVConnect HTTP API / Shelly Cloud API |
| Notifications | Telegram Bot API |
| QR generation | qrcode + Pillow |
| Frontend | Vanilla JS PWA |

## Project Structure

```
src/
├── main.py               # App entry point, startup, static file serving
├── core/
│   ├── auth.py           # JWT creation/verification, password hashing
│   ├── config.py         # Settings loaded from environment variables
│   ├── database.py       # SQLAlchemy models and DB initialization
│   ├── dependencies.py   # FastAPI dependency injection (auth guards)
│   └── schemas.py        # Pydantic request/response schemas
├── routers/
│   ├── auth.py           # POST /api/auth/admin, POST /api/auth/keypass
│   ├── gates.py          # User-facing gate list and open endpoints
│   ├── keypasses.py      # Admin keypass CRUD + QR code generation
│   ├── admins.py         # Admin user management
│   ├── credentials.py    # AVConnect credential management
│   ├── stats.py          # Access log / statistics (paginated, filtered)
│   └── telegram.py       # Telegram notification configuration
├── services/
│   ├── avconnect.py      # AVConnect API client
│   ├── gates.py          # Gate open orchestration
|   |── shelly.py         # Shelly Cloud API client
│   └── telegram.py       # Telegram Bot API client
└── static/               # Frontend PWA (index.html, admin.html, JS, CSS)
data/
└── gates.db              # SQLite database (auto-created on first run)
```

## API Endpoints

### Authentication

| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/auth/admin` | Admin login — returns JWT |
| POST | `/api/auth/keypass` | Keypass login — returns JWT |

### User (keypass token required)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/gates` | List gates accessible to the authenticated keypass |
| POST | `/api/gates/{gate_id}/open` | Open a gate |

### Admin — Gates (manager+)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/admin/gates` | List all gates |
| POST | `/api/admin/gates` | Create a gate *(admin only)* |
| PUT | `/api/admin/gates/{gate_id}` | Update a gate *(admin only)* |
| DELETE | `/api/admin/gates/{gate_id}` | Delete a gate *(admin only)* |
| POST | `/api/admin/gates/{gate_id}/open` | Manually open a gate |

### Admin — Keypasses (manager+)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/admin/keypasses` | List all keypasses |
| POST | `/api/admin/keypasses` | Create a keypass |
| PATCH | `/api/admin/keypasses/{kp_id}` | Update a keypass (description, expiry, gates, schedule) |
| DELETE | `/api/admin/keypasses/{kp_id}` | Revoke a keypass |
| GET | `/api/admin/keypasses/{kp_id}/qr` | Download QR code PNG for a keypass |

### Admin — Users (admin only)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/admin/admins` | List admin users |
| POST | `/api/admin/admins` | Create an admin user |
| DELETE | `/api/admin/admins/{username}` | Delete an admin user |
| PATCH | `/api/admin/admins/{username}/password` | Change password |
| POST | `/api/admin/admins/{username}/totp/setup` | Generate a new TOTP secret and return provisioning URI + QR |
| POST | `/api/admin/admins/{username}/totp/enable` | Verify a TOTP code and activate 2FA |
| DELETE | `/api/admin/admins/{username}/totp` | Disable 2FA and discard the secret |

### Admin — AVConnect Credentials (admin only)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/admin/credentials/avconnect` | View stored AVConnect credentials |
| PUT | `/api/admin/credentials/avconnect` | Create or update AVConnect credentials |
| GET | `/api/admin/credentials/shelly` | View stored Shelly Cloud credentials |
| PUT | `/api/admin/credentials/shelly` | Create or update Shelly Cloud credentials |
| GET | `/api/admin/credentials/mock` | Get mock mode status |
| PUT | `/api/admin/credentials/mock` | Enable or disable mock mode |

### Admin — Statistics (manager+)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/admin/stats` | Paginated, filtered access log |

Query parameters: `gate_id`, `keypass_code` (partial match), `success` (bool), `date_from`, `date_to`, `page` (default 1), `page_size` (default 50, max 200).

### Admin — Telegram Notifications (admin only)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/admin/telegram` | Get current Telegram configuration |
| PUT | `/api/admin/telegram` | Save bot token and chat ID |
| POST | `/api/admin/telegram/test` | Send a test message |

## Configuration

All settings are read from environment variables (centralised in `src/core/config.py`).

### Security

| Variable | Default | Description |
|---|---|---|
| `SECRET_KEY` | *(required)* | JWT signing key and Fernet encryption key. The application will refuse to start if this is not set. Use a long random string (`openssl rand -hex 32`). |

### Admin seed account

| Variable | Default | Description |
|---|---|---|
| `ADMIN_USERNAME` | `admin` | Username for the initial admin account created on first run. |
| `ADMIN_PASSWORD` | *(none)* | Password for the initial admin account. If unset, no seed account is created. Minimum 12 characters. |

### Server

| Variable | Default | Description |
|---|---|---|
| `APP_PORT` | `8000` | HTTP port the server listens on. |

### Database

| Variable | Default | Description |
|---|---|---|
| `DATABASE_URL` | `sqlite:///data/gates.db` | SQLAlchemy database URL. |

### Map (home location)

| Variable | Default | Description |
|---|---|---|
| `HOME_LAT` | *(none)* | WGS-84 latitude of the home/property marker shown on the frontend map. |
| `HOME_LON` | *(none)* | WGS-84 longitude of the home/property marker. |
| `HOME_NAME` | `Home` | Display name for the home marker popup. |

If `HOME_LAT` and `HOME_LON` are both set, the map is always visible. If only gates have coordinates (set per-gate in the admin panel), the map is shown only when at least one gate has a location.

### Network / reverse proxy

| Variable | Default | Description |
|---|---|---|
| `CORS_ORIGINS` | *(empty — no cross-origin requests)* | Comma-separated list of allowed CORS origins, e.g. `https://gates.example.com`. |
| `TRUSTED_PROXY_IPS` | `127.0.0.1` | Comma-separated list of reverse-proxy IPs whose `X-Forwarded-For` header is trusted for client IP resolution. |

### Logging

| Variable | Default | Description |
|---|---|---|
| `LOG_LEVEL` | `INFO` | Logging verbosity. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. |
| `LOG_FILE` | `/var/log/lagomaregates.log` | Path to the rotating log file (10 MB, 5 backups). Set to an empty string to disable file logging. |

## Running with Docker Compose

```bash
# Copy and edit the compose file to set your SECRET_KEY
docker compose up -d
```

The default `docker-compose.yml` starts the service on port `8000`. Set a strong `SECRET_KEY` and, optionally, `ADMIN_USERNAME` / `ADMIN_PASSWORD` before deploying.

The `./data` directory is mounted into the container so the SQLite database persists across restarts.

## Running Locally

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export SECRET_KEY="$(openssl rand -hex 32)"
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="changeme-at-least-12"

uvicorn src.main:app --port 8000
```

The application is then available at:

- **User interface** — `http://localhost:8000/`
- **Admin dashboard** — `http://localhost:8000/admin`

## AVConnect Integration

Gates are controlled through one of two supported API providers.

### AVConnect

Each gate is mapped to an AVConnect *macro ID*. When a gate open request is received, the service:

1. Authenticates with AVConnect using the stored credentials (session is cached in the database)
2. Executes the configured macro for the gate

Credentials (password) are stored encrypted in the database using Fernet symmetric encryption derived from `SECRET_KEY`.

### Shelly Cloud

Each gate is mapped to a Shelly *device ID*. The service calls the Shelly Cloud API with the stored auth key to activate the device's relay.

The Shelly server URI and auth key are stored encrypted. Configure them under **Admin → Credentials → Shelly Cloud**.

**Mock mode** — when enabled via the admin dashboard, gate open requests always succeed without contacting any external API. Useful for testing.

## Keypass Schedules

In addition to an expiry date and a per-gate allowlist, each keypass can be restricted to a configurable time window:

- **Days of the week** — select any combination of Mon–Sun. If no day is checked the restriction applies on any day.
- **Time window** — a `From` / `To` time in 24-hour format (server local time). Both values must be provided together.

When a keypass with a schedule is used outside its allowed window the API returns **HTTP 403** (`Keypass is not valid today` / `Keypass is not valid at this time`) and the gate will not open. The restriction is enforced in `require_keypass` in `src/core/dependencies.py`.

The schedule is stored as a JSON object in the `schedule` column of the `keypasses` table:

```json
{ "days": [0, 1, 2, 3, 4], "time_start": "08:00", "time_end": "18:00" }
```

`days` uses Python's `weekday()` convention: 0 = Monday, 6 = Sunday. Any absent key is treated as unrestricted (e.g. omitting `days` means any day is allowed).

## Keypass QR Codes

Each active keypass has a **QR** button in the admin panel. Clicking it generates a PNG QR code that encodes the URL:

```
https://<your-domain>/?k=<KEYPASS_CODE>
```

Scanning the code with a phone opens the web app and logs in automatically. If the keypass is expired or revoked, the user is shown an error on the login screen.

## Telegram Notifications

Configure a Telegram bot to receive a message in a group or chat every time a gate is opened:

1. Create a bot via [@BotFather](https://t.me/BotFather) and copy the token
2. Add the bot to your group and obtain the chat ID (e.g. using [@userinfobot](https://t.me/userinfobot))
3. Open **Admin → Notifications**, enter the token and chat ID, and click **Save**
4. Use **Send test message** to verify the setup

Notifications are sent in a background thread and never block the gate open response. Failures are logged as warnings and do not affect gate operation.

## Two-Factor Authentication (TOTP)

Each admin account can independently enable TOTP-based two-factor authentication:

1. Open **Admin → Admin Users** and click **Enable 2FA** on your own row
2. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.)
3. Enter the 6-digit code to confirm — 2FA is only activated after a successful verification
4. On subsequent logins, after entering your password you will be prompted for the current TOTP code

To disable, click **Disable 2FA** on your row and confirm.

> Only the account owner can enable or disable their own 2FA. TOTP secrets are stored Fernet-encrypted in the database.

## Roles

| Role | Permissions |
|---|---|
| `admin` | Full access — all endpoints including gate/user/credential/notification management |
| `manager` | Gate open, keypass management, statistics — cannot manage admin users, AVConnect credentials, gate configuration, or Telegram settings |