npm - @hanoilab/zk-bridge - Versions diffs - 0.1.4 → 0.1.5 - Mend

@hanoilab/zk-bridge 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +180 -103
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,43 +1,119 @@
-# @hanoilab/zk-bridge
+<p align="center">
+  <img src="https://img.shields.io/badge/ZK--Bridge-Attendance-007ACC?style=for-the-badge&logo=fingerprint&logoColor=white" alt="ZK-Bridge" />
+</p>
-LAN-side bridge for ZKTeco attendance devices. Polls a device over TCP and pushes events to your backend over HTTPS.
+<h1 align="center">ZK-Bridge</h1>
+<p align="center">
+  <strong>LAN-side bridge for ZKTeco attendance devices.</strong><br/>
+  Polls a ZKTeco fingerprint reader over TCP, pushes events to any HTTP backend.
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@hanoilab/zk-bridge">npm</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#features">Features</a> &bull;
+  <a href="#how-it-works">How It Works</a> &bull;
+  <a href="#backend-contract">Backend Contract</a> &bull;
+  <a href="#self-hosting">Self-Hosting</a>
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@hanoilab/zk-bridge"><img src="https://img.shields.io/npm/v/@hanoilab/zk-bridge?style=flat-square&color=cb3837&label=npm" alt="npm" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D20.0.0-339933?style=flat-square&logo=node.js&logoColor=white" alt="node" />
+  <img src="https://img.shields.io/badge/sqlite-bundled-003B57?style=flat-square&logo=sqlite&logoColor=white" alt="sqlite" />
+  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license" />
+</p>
+---
+## What is this?
+ZKTeco fingerprint readers don't speak HTTP — they only accept TCP connections from inside the LAN, and the C-HR / HRIS backend lives in the cloud. ZK-Bridge sits in the office, polls the device on a schedule, and pushes attendance events to any HTTP API you point it at.
+```
+ZKTeco device                ZK-Bridge                  Your backend
+┌─────────────────┐       ┌──────────────┐           ┌──────────────┐
+│ Fingerprint /   │ ◄─TCP─┤  CLI + UI    │ ◄──HTTPS──┤  /push       │
+│ face reader     │ 4370  │  SQLite      │           │  /ping       │
+│ 192.168.x.y     │       │  Local LAN   │           │  Cloud / VPS │
+└─────────────────┘       └──────────────┘           └──────────────┘
+                          Outbound only — no port
+                          forwarding or VPN needed
+```
+No vendor lock-in: any backend that exposes a JSON `POST` endpoint with a JWT auth header works. Bridge handles the LAN side.
 ## Quick Start
+### 1. Install globally
 ```bash
-# Install globally
 npm i -g @hanoilab/zk-bridge
+```
+### 2. Run it
-# Start the bridge
+```bash
 zk-bridge start
 ```
-That's it. You'll see:
 ```text
 [zk-bridge] data dir: ~/.local/share/zk-bridge
 [zk-bridge] UI listening on http://127.0.0.1:7000
 [scheduler] starting cron "*/5 * * * *" (every 5 min)
+[zk-bridge] running. Press Ctrl+C to stop.
 ```
-Open the admin UI, paste your backend's Push URL + a per-device JWT, and the bridge starts pushing on the next cycle.
+### 3. Open the admin UI
-## Features
+Visit **<http://localhost:7000>**, set the backend Push URL, paste the per-device JWT — bridge pushes attendance on the next cycle.
-- **Web admin UI** — Single-user login, device list, scan LAN, view events
-- **LAN scan** — Auto-discover ZKTeco devices on your subnet (TCP 4370)
-- **Multi-device** — One bridge polls many devices on a schedule
-- **Offline tolerant** — Queues events when the backend is unreachable, drains on next cycle
-- **Idempotent push** — Backend dedupes by `(deviceId, eventLogId)`; safe to retry
-- **Auto-start on boot** — One-click systemd / Windows Task / launchd registration
-- **Cross-platform** — Linux, macOS, Windows
-- **Secure** — bcrypt admin login, signed-cookie sessions, JWT per-device tokens
+## Features
-## CLI Commands
+### Web Admin UI
+- Single-user login (bcrypt + signed-cookie session, 7-day TTL)
+- Configure backend Push / Ping URL + poll interval
+- Add devices manually or via LAN scan
+- Per-device events with cursor position + push status badge
+- Cycle history with status, timing, error message, filter by device
+### LAN Discovery
+- Auto-scan `/24` subnet for ZKTeco devices on TCP 4370
+- Identify each candidate over the ZK protocol (model, serial)
+- One-click "Add as device" pre-fills name + host
+### Multi-Device
+- One bridge polls many devices on a single schedule
+- Per-device cursor, queue, audit log, error state
+- Enable / disable individually without removing config
+### Offline Tolerance
+- Queues events to local SQLite when the backend is unreachable
+- Drains the queue on the next online cycle
+- Cursor advances even on partial failure — no data loss, no double-send
+### Idempotent Push
+- Backend dedupes by `(deviceId, eventLogId)` — replay is a no-op
+- Batches events at 200/request to stay under common body-parser limits
+- JWT version counter for revocation (regenerate on the backend → old JWTs rejected immediately)
+### Auto-Start on Boot
+- One-click toggle in the System page registers a:
+  - **systemd** unit (Linux)
+  - **Scheduled Task** (Windows)
+  - **launchd** plist (macOS)
+- `Restart=on-failure` so a crashed cycle never takes the bridge down
+### Cross-platform
+- Linux, macOS, Windows
+- Node 20+ — no native build needed (sqlite3 ships prebuilds)
+## CLI
 ```bash
-zk-bridge start                  # Start bridge (UI + scheduler) — default
-zk-bridge poll-once              # One cycle then exit
+zk-bridge start                  # Start bridge (UI + scheduler)
+zk-bridge poll-once              # Run a single cycle then exit
 zk-bridge reset-user             # Forgot-password recovery
 zk-bridge recent-events          # Print last N events from a device
 zk-bridge upgrade [tag]          # Self-update via npm
@@ -45,28 +121,15 @@ zk-bridge --help
 zk-bridge --version
 ```
-## Admin Panel
-After `zk-bridge start`, open `http://localhost:7000` to:
+Environment overrides (otherwise default):
-- Set the backend Push URL + Ping URL + poll interval
-- Add devices (manual or via LAN scan)
-- View per-device events with cursor position, push status
-- Inspect cycle history, reset cursor, regenerate tokens
-- Toggle auto-start on boot
+```bash
+PORT=8080 BIND_HOST=0.0.0.0 zk-bridge start
+DATA_DIR=/var/lib/zk-bridge zk-bridge start
+```
 ## How It Works
-```text
-ZK device              zk-bridge              Your backend
-+----------+         +-----------+         +------------+
-|  ZKTeco  | <-----> |  bridge   | <-----> |  HTTP API  |
-| TCP 4370 |   ZK    | (this CLI)|  HTTPS  | /push      |
-+----------+         +-----------+         +------------+
-                        SQLite
-                     (config + queue)
-```
 Every cycle (default 5 min):
 1. List enabled devices in local SQLite.
@@ -74,20 +137,32 @@ Every cycle (default 5 min):
 3. Drain the offline queue, then push new events to the backend in batches of 200.
 4. Advance the cursor, write a `cycle_log` row.
-Backend dedupes by `(deviceId, eventLogId)` — replays are safe.
+State that lives locally:
+```
+~/.local/share/zk-bridge/zk-bridge.db   (Linux default)
+%APPDATA%\zk-bridge\zk-bridge.db        (Windows)
+~/Library/Application Support/zk-bridge/zk-bridge.db  (macOS)
+  ├── users          (single admin row)
+  ├── config         (push URL, ping URL, poll interval, session secret)
+  ├── devices        (host, port, JWT, cursor, last status)
+  ├── event_queue    (offline-pending events)
+  └── cycle_log      (per-device cycle history, rotated to last 1000)
+```
 ## Backend Contract
-The bridge POSTs to **two URLs** you configure:
+Two HTTP endpoints. Configure their full URLs in the UI — the bridge appends nothing.
-**Push URL** (required)
+### Push (required)
 ```http
 POST <push-url>
 Content-Type: application/json
 {
-  "token": "<JWT>",
+  "token": "<JWT signed by backend>",
   "events": [
     {
       "eventLogId": "12345",
@@ -99,7 +174,16 @@ Content-Type: application/json
 }
 ```
-**Ping URL** (optional — used by the *Connect* button)
+The backend should:
+- Verify the JWT (signature + expiry / version).
+- Resolve the device row from the JWT payload.
+- Dedupe by `(deviceId, eventLogId)` — replays are safe.
+- Persist or normalize the events as needed.
+Response shape isn't enforced — bridge only checks the HTTP status (2xx = success, anything else = retry / queue).
+### Ping (optional)
 ```http
 POST <ping-url>
@@ -108,100 +192,93 @@ Content-Type: application/json
 { "token": "<JWT>" }
 ```
-If you don't expose a separate ping endpoint, leave the field empty — the bridge falls back to a push with an empty events array.
-The backend is responsible for: verifying the JWT, resolving devices, deduping by `(deviceId, eventLogId)`, and storing or normalizing events.
-## Requirements
-- Node.js 20+
-- macOS, Linux, or Windows
-- Network reach: bridge host must see the ZK device on LAN AND the backend over HTTP(S)
+Used by the **Connect** button to verify the JWT + URL without sending events. If you don't expose a separate ping endpoint, leave the field blank — the bridge falls back to a push with an empty `events` array (your backend should respond 4xx for that case, which the bridge interprets as "auth + URL OK").
-## Configuration
+### Reference implementation
-Settings live in a local SQLite DB and are edited through the web UI. Only paths and bind come from env:
+See [c-hr backend](https://github.com/nguyendinhphongdx/c-hr) — `apps/backend/src/apps/attendance/attendance-device/` is a NestJS module that implements the contract end-to-end, including JWT version revocation and orphan-event reconcile.
-| Env | Default | Purpose |
-| --- | --- | --- |
-| `DATA_DIR` | OS-standard (see below) | Where SQLite + admin login live |
-| `PORT` | `7000` | UI HTTP port |
-| `BIND_HOST` | `127.0.0.1` | Listen address. Set `0.0.0.0` for LAN access |
+## Self-Hosting
-**Data dir resolution:**
-- `DATA_DIR` env (always wins)
-- `./data/` next to cwd, if it exists (Docker bind mount, dev workflow)
-- Globally installed: OS-standard user data dir
-  - Linux: `~/.local/share/zk-bridge`
-  - macOS: `~/Library/Application Support/zk-bridge`
-  - Windows: `%APPDATA%\zk-bridge`
+```bash
+git clone https://github.com/nguyendinhphongdx/zkteco-bridge.git
+cd zkteco-bridge
+pnpm install
+pnpm build
+pnpm start
+```
-Boot prints the chosen path:
+Or install your local checkout as the global CLI:
-```text
-[2026-05-07T08:23:45.123Z] [zk-bridge] data dir: ~/.local/share/zk-bridge
+```bash
+npm install -g .
+zk-bridge start
 ```
-## Auto-start on Host
+### Auto-start (production)
-Three options — pick one:
+Three options — pick **one**, otherwise two processes will fight for port 7000:
-- **Built-in toggle** (recommended): *System → Auto-start on boot* in the web UI registers a systemd unit / Windows Scheduled Task / launchd plist with `Restart=on-failure`.
-- **PM2**:
+- **Built-in toggle** (recommended) — *System → Auto-start on boot* registers a systemd / Windows Task / launchd entry pointing at the global CLI binary.
+- **PM2** —
   ```bash
   pm2 start "$(which zk-bridge)" --name zk-bridge -- start
   pm2 startup && pm2 save
   ```
-- **Docker** — see [`docker-compose.yml`](docker-compose.yml). Bind-mount `./data:/app/data` to persist state.
+- **Docker** — see [`docker-compose.yml`](docker-compose.yml). Bind-mount `./data:/app/data` to persist SQLite across rebuilds.
-Don't enable two methods at once — they'll fight for port 7000.
+## Environment Variables
-## Self-upgrade
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `7000` | Admin UI HTTP port |
+| `BIND_HOST` | `127.0.0.1` | Listen address. Set `0.0.0.0` to allow LAN access |
+| `DATA_DIR` | OS-standard user data dir | Override SQLite + admin login location |
+| `PUSH_URL` | _(none)_ | First-run seed only — bridge stores it in SQLite then ignores env |
+| `PING_URL` | _(none)_ | First-run seed only |
+| `POLL_INTERVAL_MIN` | `5` | First-run seed only — minutes between cycles |
-```bash
-zk-bridge upgrade
-sudo systemctl restart zk-bridge   # or pm2 restart zk-bridge / docker compose pull
-```
+`DATA_DIR` resolution order on every start:
-`zk-bridge upgrade` runs `npm install -g <pkg>@latest` under the hood. Restart the host service afterwards so the running process picks up new code.
+1. `DATA_DIR` env var (always wins)
+2. `./data/` next to cwd, if it exists (Docker bind mount, dev workflow)
+3. **Globally installed:** OS-standard user data dir
+4. `./data/` next to cwd (dev fallback)
 ## Troubleshooting
 | Symptom | Likely cause / fix |
-| --- | --- |
-| `ETIMEDOUT <ip>:<port>` on Connect | Bridge can't reach the backend Push URL from this host. `curl <url>` from the host should work. |
-| `HTTP 401 Invalid token` | JWT was regenerated on the backend or device deleted. Re-paste the token. |
+|---------|-------------------|
+| `ETIMEDOUT <ip>:<port>` on Connect | Bridge can't reach the backend Push URL. `curl <url>` from the bridge host should work. |
+| `HTTP 401 Invalid token` | JWT was regenerated on the backend, or the device row was deleted. Re-paste the token. |
 | `Socket closed unexpectedly` | The ZK device only allows 1 active connection — another tool / cycle is holding it. Wait for the next cycle. |
-| `port open but ZK probe fail` in scan | Same — device is busy. Try Add → Connect after a minute. |
+| `port open but ZK probe fail` in scan | Same — device is busy. Try **Add** → **Connect** after a minute. |
 | Dashboard shows "never run" | Push URL not set, or no devices configured. Check *API settings* + *Devices*. |
-| Events arrive late | Lower the poll interval in *API settings* (min 1 min). |
+| Events arrive late | Lower the *poll interval* in *API settings* (min 1 min). |
-Every console line is prefixed with an ISO timestamp:
+Every console line is prefixed with an ISO timestamp so logs from `pm2 logs` / `journalctl -u zk-bridge` / `docker compose logs` line up:
 ```text
 [2026-05-07T08:23:50.747Z] [poll] "Front gate" pulled 2915 from ZK in 5291ms
 ```
-## Develop from source
-```bash
-git clone https://github.com/nguyendinhphongdx/c-hr.git
-cd c-hr/services/zk-bridge
-pnpm install
-pnpm build
-pnpm start
-```
-The package is standalone — it has its own `pnpm-workspace.yaml` and `pnpm-lock.yaml`, separate from any parent monorepo. Install your local copy as the global CLI:
+## Tech Stack
-```bash
-npm install -g .
-zk-bridge start
-```
+| Layer | Technology |
+|-------|-----------|
+| Runtime | [Node.js 20+](https://nodejs.org/) |
+| Local DB | [SQLite](https://www.sqlite.org/) via [sqlite3](https://github.com/TryGhost/node-sqlite3) + [Sequelize](https://sequelize.org/) |
+| HTTP server | [Hono](https://hono.dev/) + [@hono/node-server](https://github.com/honojs/node-server) |
+| ZK protocol | Custom client (`src/zklib`) — TCP raw, chunked streaming for large logs |
+| Auth | [bcryptjs](https://github.com/dcodeIO/bcrypt.js) (admin) + JWT (per-device) |
+| HTTP client | [axios](https://axios-http.com/) |
+| Scheduler | [node-cron](https://github.com/node-cron/node-cron) |
+| Build | [TypeScript](https://www.typescriptlang.org/) |
 ## License
-MIT
+MIT &copy; [HanoiLab](mailto:opencode@hanoilab.vn)
+---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hanoilab/zk-bridge",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "description": "Pull-side bridge for ZKTeco attendance devices — polls over LAN and pushes events to any HTTP backend",
   "keywords": [