@alizadefaig/pos-server 1.2.26 → 1.2.28

package/app/sync/discovery.js

@@ -0,0 +1,546 @@
+const dgram = require('node:dgram');
+const os = require('node:os');
+const {createHmac, randomBytes, timingSafeEqual} = require('node:crypto');
+const config = require('./config');
+const {subnetHosts} = require('../printers/address');
+
+/**
+ * Автопоиск мастера в зале (OFFLINE-FIRST-PLAN §12.8, P2): OFFLINE_MASTER_URL=auto вместо
+ * жёсткого http://192.168.1.10:3005 — ведомому не нужно знать адрес мастера, а смена адреса
+ * мастера по DHCP не оставляет зал без кассы.
+ *
+ * Протокол — запрос/ответ, а не маяк мастера:
+ *   ведомый → широковещательно {t:'cafepos-discover', v, nonce, company_id?}
+ *   мастер  → адресно ведомому {t:'cafepos-master', v, nonce, port, company_id, terminal_id,
+ *                               hosts, proof}
+ *   proof = HMAC-SHA256(lan_key, 'cafepos-discover|v|nonce|port|company_id|terminal_id|hosts')
+ *
+ * Почему так:
+ * - ведомый шлёт ключ зала только на адрес, который доказал знание этого ключа. Ключ в сети не
+ *   летает, а ответ без ключа не подделать;
+ * - nonce свежий на каждый запрос — записанный ответ повторить нельзя, часы касс не участвуют;
+ * - hosts (свои IPv4 мастера) входят в подпись, и ведомый принимает ответ только с адреса из
+ *   этого списка: чужое устройство, переславшее настоящий ответ от своего имени, не подойдёт;
+ * - ответ на широковещательный запрос Windows Firewall пропускает по умолчанию, так что у
+ *   ведомого не нужен входящий UDP-порт — правило брандмауэра нужно только мастеру (тот же
+ *   exe, что уже слушает 0.0.0.0:3005).
+ *
+ * Ведомый ищет мастера по ступеням (как evopos), от дешёвой к дорогой:
+ *   1. известный адрес — текущий или сохранённый с прошлого запуска (kv): один HTTP-запрос;
+ *   2. широковещательный UDP-запрос;
+ *   3. скан своей подсети (не шире /24) по HTTP — когда широковещание не доходит: точка доступа
+ *      фильтрует broadcast или брандмауэр мастера пропускает TCP 3005, но не UDP. Изоляцию
+ *      клиентов Wi-Fi скан не обходит — там режется любой трафик между устройствами.
+ *      Не чаще раза в OFFLINE_DISCOVERY_SCAN_MS.
+ * По HTTP мастер отвечает на GET /local/whoami?nonce= тем же подписанным ответом, что и по UDP,
+ * и ведомый проверяет его той же функцией (accept). Ключ зала в запросе не передаётся.
+ *
+ * Работает только при включённом синке и заданном ключе зала: мастер без ключа слушает только
+ * localhost (см. lan.js) — искать его в сети бессмысленно.
+ */
+
+const VERSION = 1;
+const QUERY = 'cafepos-discover';
+const ANSWER = 'cafepos-master';
+const MAX_PACKET = 2048;
+// мастер отвечает не чаще — поддельные запросы с чужим адресом не превратят его в усилитель
+const MAX_ANSWERS_PER_SECOND = 20;
+// скан подсети по HTTP: адресов за раз и сколько ждать каждый (в LAN мастер отвечает за мс)
+const SCAN_BATCH = 48;
+const SCAN_TIMEOUT_MS = 400;
+// проверка известного адреса (ступень 1)
+const VERIFY_TIMEOUT_MS = 1000;
+const IPV4 = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+const log = (...args) => console.log('[discovery]', ...args);
+
+const num = (name, fallback) => {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+};
+
+const settings = () => ({
+    port: num('OFFLINE_DISCOVERY_PORT', 3005),
+    // пока мастер не найден или не отвечает — спрашиваем часто, нашли — только проверяем
+    interval: num('OFFLINE_DISCOVERY_MS', 3000),
+    // сколько ждать ответы на один запрос
+    window: num('OFFLINE_DISCOVERY_WINDOW_MS', 1500),
+    // скан подсети (ступень 3): HTTP-порт мастера — по соглашению тот же 3005
+    scan: process.env.OFFLINE_DISCOVERY_SCAN !== 'false',
+    scanInterval: num('OFFLINE_DISCOVERY_SCAN_MS', 30000),
+    httpPort: num('OFFLINE_DISCOVERY_HTTP_PORT', 3005),
+});
+
+const sign = (key, fields) => createHmac('sha256', key)
+    .update([QUERY, VERSION, fields.nonce, fields.port, fields.company_id || '', fields.terminal_id || '',
+        [...fields.hosts].sort().join(',')].join('|'))
+    .digest('hex');
+
+const proofMatches = (key, fields, proof) => {
+    if (typeof proof !== 'string' || !/^[0-9a-f]{64}$/.test(proof)) {
+        return false;
+    }
+    const expected = Buffer.from(sign(key, fields), 'hex');
+    return timingSafeEqual(expected, Buffer.from(proof, 'hex'));
+};
+
+/** Свои IPv4 и широковещательные адреса подсетей (0 = нет интерфейсов). */
+const interfaces = () => {
+    const result = [];
+    for (const list of Object.values(os.networkInterfaces())) {
+        for (const item of list || []) {
+            if (item.family !== 'IPv4' && item.family !== 4) {
+                continue;
+            }
+            if (item.internal) {
+                continue;
+            }
+            const address = item.address.split('.').map(Number);
+            const mask = String(item.netmask || '255.255.255.0').split('.').map(Number);
+            const broadcast = address.map((part, i) => (part | (~mask[i] & 255))).join('.');
+            result.push({address: item.address, broadcast});
+        }
+    }
+    return result;
+};
+
+const parse = (buffer) => {
+    if (!buffer || buffer.length > MAX_PACKET) {
+        return null;
+    }
+    try {
+        const message = JSON.parse(buffer.toString('utf8'));
+        return message && typeof message === 'object' && message.v === VERSION ? message : null;
+    } catch (e) {
+        return null;
+    }
+};
+
+const send = (socket, message, port, address) => new Promise((resolve) => {
+    const buffer = Buffer.from(JSON.stringify(message));
+    socket.send(buffer, port, address, (error) => resolve(!error));
+});
+
+/** Не больше max ответов в секунду. */
+class Limiter {
+    constructor(max) {
+        this.max = max;
+        this.second = 0;
+        this.count = 0;
+    }
+
+    take() {
+        const second = Math.floor(Date.now() / 1000);
+        if (second !== this.second) {
+            this.second = second;
+            this.count = 0;
+        }
+        this.count += 1;
+        return this.count <= this.max;
+    }
+}
+
+/**
+ * Подписанный ответ мастера на nonce — одинаковый для UDP и /local/whoami. null — отвечать
+ * нечего: нет ключа зала, нет сессии кассы или nonce не похож на наш.
+ */
+const buildAnswer = ({nonce, httpPort, identity}) => {
+    const key = config.lanKey();
+    if (!key || !identity || !identity.company_id) {
+        return null;
+    }
+    const value = String(nonce || '');
+    if (!/^[0-9a-f]{32,64}$/.test(value)) {
+        return null;
+    }
+    const fields = {
+        nonce: value,
+        port: Number(httpPort) || 3005,
+        company_id: identity.company_id,
+        terminal_id: identity.terminal_id || '',
+        hosts: interfaces().map((item) => item.address),
+    };
+    if (!fields.hosts.length) {
+        return null;
+    }
+    return {t: ANSWER, v: VERSION, ...fields, proof: sign(key, fields)};
+};
+
+/**
+ * Проверка ответа мастера (UDP и HTTP). address — откуда ответ пришёл на самом деле: он обязан
+ * быть в подписанных hosts. port — если известен (HTTP): мастер обязан назвать тот же.
+ */
+const accept = (message, {key, nonce, address, companyId = null, port = null}) => {
+    if (!message || message.t !== ANSWER || message.nonce !== nonce) {
+        return null;
+    }
+    const hosts = Array.isArray(message.hosts) ? message.hosts.map(String) : [];
+    const fields = {
+        nonce,
+        port: Number(message.port),
+        company_id: String(message.company_id || ''),
+        terminal_id: String(message.terminal_id || ''),
+        hosts,
+    };
+    if (!Number.isInteger(fields.port) || fields.port <= 0 || fields.port > 65535) {
+        return null;
+    }
+    if (port !== null && fields.port !== port) {
+        return null;
+    }
+    if (!hosts.includes(address) || !proofMatches(key, fields, message.proof)) {
+        return null;
+    }
+    if (companyId && fields.company_id !== companyId) {
+        return null;
+    }
+    return {
+        url: `http://${address}:${fields.port}`,
+        address,
+        port: fields.port,
+        company_id: fields.company_id,
+        terminal_id: fields.terminal_id,
+    };
+};
+
+// ---------------------------------------------------------------- мастер: отвечает
+
+class Responder {
+    /**
+     * @param {{httpPort: () => number, identity: () => ({company_id, terminal_id}|null)}} options
+     *   identity — кто мы сейчас (сессия кассы); нет сессии — не отвечаем: ведомому нечего
+     *   сверять, а зал без залогиненного мастера всё равно не обслуживается.
+     */
+    constructor({httpPort, identity}) {
+        this.httpPort = httpPort;
+        this.identity = identity;
+        this.socket = null;
+        this.answered = 0;
+        this.limiter = new Limiter(MAX_ANSWERS_PER_SECOND);
+    }
+
+    start() {
+        if (this.socket) {
+            return this;
+        }
+        const {port} = settings();
+        // Без reuseAddr: на Windows он позволил бы другой программе занять тот же порт.
+        const socket = dgram.createSocket('udp4');
+        socket.on('error', (e) => {
+            console.warn('[discovery] responder error:', e.message);
+            this.stop();
+        });
+        socket.on('message', (buffer, rinfo) => {
+            this.answer(socket, parse(buffer), rinfo).catch(() => {});
+        });
+        socket.bind(port, () => log(`answering on udp/${port}`));
+        socket.unref();
+        this.socket = socket;
+        return this;
+    }
+
+    async answer(socket, message, rinfo) {
+        if (!message || message.t !== QUERY) {
+            return;
+        }
+        const identity = this.identity();
+        // Ведомый другого заведения в той же сети — не наш.
+        if (identity && message.company_id && message.company_id !== identity.company_id) {
+            return;
+        }
+        const answer = buildAnswer({nonce: message.nonce, httpPort: this.httpPort(), identity});
+        if (!answer || !this.limiter.take()) {
+            return;
+        }
+        this.answered += 1;
+        await send(socket, answer, rinfo.port, rinfo.address);
+    }
+
+    stop() {
+        if (this.socket) {
+            const socket = this.socket;
+            this.socket = null;
+            try {
+                socket.close();
+            } catch (e) {
+                // уже закрыт
+            }
+        }
+    }
+}
+
+const httpLimiter = new Limiter(MAX_ANSWERS_PER_SECOND);
+let httpAnswered = 0;
+
+/**
+ * GET /local/whoami?nonce= — тот же подписанный ответ по HTTP (ступени 1 и 3 поиска). Путь
+ * открыт без ключа зала (lan.js): ответ сам доказывает знание ключа и ничего не раскрывает.
+ * null — не отвечаем (не мастер, нет ключа или сессии, превышен лимит).
+ */
+const whoami = ({nonce, httpPort, identity}) => {
+    const answer = buildAnswer({nonce, httpPort, identity});
+    if (!answer || !httpLimiter.take()) {
+        return null;
+    }
+    httpAnswered += 1;
+    return answer;
+};
+
+// ---------------------------------------------------------------- ведомый: ищет
+
+/**
+ * Один раунд поиска: широковещательный запрос во все подсети, проверка ответов в течение
+ * window. Отдаёт проверенных кандидатов (без дублей по адресу).
+ *
+ * @param {{companyId?: string, targets?: string[]}} options
+ *   targets — куда слать вместо широковещательных адресов (тесты, сети без broadcast).
+ */
+const probe = ({companyId = null, targets = null} = {}) => new Promise((resolve) => {
+    const key = config.lanKey();
+    if (!key) {
+        resolve([]);
+        return;
+    }
+    const {port, window} = settings();
+    const nonce = randomBytes(16).toString('hex');
+    const found = new Map();
+    const socket = dgram.createSocket('udp4');
+    let finished = false;
+    const finish = () => {
+        if (finished) {
+            return;
+        }
+        finished = true;
+        clearTimeout(timer);
+        try {
+            socket.close();
+        } catch (e) {
+            // уже закрыт
+        }
+        resolve([...found.values()]);
+    };
+    const timer = setTimeout(finish, window);
+
+    socket.on('error', finish);
+    socket.on('message', (buffer, rinfo) => {
+        const candidate = accept(parse(buffer), {key, nonce, address: rinfo.address, companyId});
+        if (candidate) {
+            found.set(rinfo.address, candidate);
+        }
+    });
+    socket.bind(0, async () => {
+        socket.setBroadcast(true);
+        const message = {t: QUERY, v: VERSION, nonce, ...(companyId ? {company_id: companyId} : {})};
+        const addresses = targets && targets.length
+            ? targets
+            : [...new Set([...interfaces().map((item) => item.broadcast), '255.255.255.255'])];
+        await Promise.all(addresses.map((address) => send(socket, message, port, address)));
+    });
+});
+
+/**
+ * Проверка адреса по HTTP: GET <url>/local/whoami со свежим nonce. Отдаёт кандидата или null.
+ * Только http и IPv4 — подпись мастера перечисляет его IPv4, по имени хоста её не сверить.
+ */
+const verify = async (url, {companyId = null, timeout = VERIFY_TIMEOUT_MS} = {}) => {
+    const key = config.lanKey();
+    let target;
+    try {
+        target = new URL(url);
+    } catch (e) {
+        return null;
+    }
+    if (!key || target.protocol !== 'http:' || !IPV4.test(target.hostname)) {
+        return null;
+    }
+    const port = Number(target.port || 80);
+    const nonce = randomBytes(16).toString('hex');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetch(`http://${target.hostname}:${port}/local/whoami?nonce=${nonce}`, {
+            signal: controller.signal,
+            redirect: 'error',
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const body = Buffer.from(await response.arrayBuffer());
+        return accept(parse(body), {key, nonce, address: target.hostname, companyId, port});
+    } catch (e) {
+        return null;
+    } finally {
+        clearTimeout(timer);
+    }
+};
+
+/**
+ * Скан подсети по HTTP пачками по SCAN_BATCH. Останавливается на первой пачке, где кто-то
+ * ответил. hosts — вместо своей подсети (тесты).
+ */
+const scan = async ({companyId = null, hosts = null, port = settings().httpPort} = {}) => {
+    const list = hosts || subnetHosts();
+    for (let i = 0; i < list.length; i += SCAN_BATCH) {
+        const answers = await Promise.all(list.slice(i, i + SCAN_BATCH)
+            .map((host) => verify(`http://${host}:${port}`, {companyId, timeout: SCAN_TIMEOUT_MS})));
+        const found = answers.filter(Boolean);
+        if (found.length) {
+            return found;
+        }
+    }
+    return [];
+};
+
+class Finder {
+    /**
+     * @param {{companyId: () => (string|null), isReachable: () => (boolean|null),
+     *          onChange: (url: string|null) => void, targets?: string[]}} options
+     *   isReachable — жив ли текущий мастер по последней проверке /local/status: пока жив,
+     *   сеть не опрашиваем;
+     *   onChange — найден другой адрес (перезапуск моста к мастеру);
+     *   remembered / remember — адрес с прошлого запуска и его сохранение (ступень 1);
+     *   scanHosts — кого сканировать вместо своей подсети (тесты).
+     */
+    constructor({companyId, isReachable, onChange, targets = null, remembered = () => null,
+        remember = () => {}, scanHosts = null}) {
+        this.companyId = companyId;
+        this.isReachable = isReachable;
+        this.onChange = onChange;
+        this.targets = targets;
+        this.remembered = remembered;
+        this.remember = remember;
+        this.scanHosts = scanHosts;
+        this.lastScanAt = null;
+        this.via = null;
+        this.timer = null;
+        this.running = false;
+        this.stopped = true;
+        this.current = null;
+        this.lastProbeAt = null;
+        this.lastFoundAt = null;
+        this.candidates = [];
+        this.conflict = false;
+    }
+
+    start() {
+        if (!this.stopped) {
+            return this;
+        }
+        this.stopped = false;
+        this.schedule(0);
+        return this;
+    }
+
+    schedule(delay) {
+        clearTimeout(this.timer);
+        if (this.stopped) {
+            return;
+        }
+        this.timer = setTimeout(() => this.run(), delay);
+        if (this.timer.unref) {
+            this.timer.unref();
+        }
+    }
+
+    /** Внеочередной поиск (мастер перестал отвечать). */
+    kick() {
+        if (!this.running) {
+            this.schedule(0);
+        }
+    }
+
+    async run() {
+        if (this.stopped || this.running) {
+            return;
+        }
+        this.running = true;
+        try {
+            if (!this.current || this.isReachable() === false) {
+                await this.search();
+            }
+        } catch (e) {
+            console.warn('[discovery] probe failed:', e.message);
+        } finally {
+            this.running = false;
+        }
+        this.schedule(settings().interval);
+    }
+
+    async search() {
+        this.lastProbeAt = new Date().toISOString();
+        const companyId = this.companyId();
+        let candidates = [];
+        let via = null;
+        // 1. известный адрес: текущий или сохранённый с прошлого запуска
+        const known = [...new Set([this.current, this.remembered()].filter(Boolean))];
+        for (const url of known) {
+            const candidate = await verify(url, {companyId});
+            if (candidate) {
+                candidates = [candidate];
+                via = 'saved';
+                break;
+            }
+        }
+        // 2. широковещательный запрос
+        if (!candidates.length && !this.stopped) {
+            candidates = await probe({companyId, targets: this.targets});
+            via = 'udp';
+        }
+        // 3. скан подсети — широковещание могло не дойти (фильтр точки доступа, брандмауэр)
+        if (!candidates.length && !this.stopped && this.scanDue()) {
+            this.lastScanAt = Date.now();
+            candidates = await scan({companyId, hosts: this.scanHosts});
+            via = 'scan';
+        }
+        if (this.stopped) {
+            return;
+        }
+        this.candidates = candidates;
+        if (!candidates.length) {
+            return;
+        }
+        this.via = via;
+        // Два мастера одного заведения в сети — ошибка настройки. Держимся текущего, если он среди
+        // них, иначе берём первого по адресу (детерминированно для всех ведомых зала).
+        this.conflict = candidates.length > 1;
+        if (this.conflict) {
+            console.warn(`[discovery] several masters answer: ${candidates.map((c) => c.url).join(', ')}`);
+        }
+        const keep = this.current && candidates.find((c) => c.url === this.current);
+        const chosen = keep || [...candidates].sort((a, b) => a.address.localeCompare(b.address))[0];
+        this.lastFoundAt = new Date().toISOString();
+        if (chosen.url !== this.current) {
+            log(`master ${this.current ? `moved ${this.current} → ` : 'found at '}${chosen.url}`);
+            this.current = chosen.url;
+            config.setDiscoveredMasterUrl(chosen.url);
+            this.remember(chosen.url);
+            this.onChange(chosen.url);
+        }
+    }
+
+    scanDue() {
+        const {scan: enabled, scanInterval} = settings();
+        return enabled && (this.lastScanAt === null || Date.now() - this.lastScanAt >= scanInterval);
+    }
+
+    status() {
+        return {
+            url: this.current,
+            last_probe_at: this.lastProbeAt,
+            last_found_at: this.lastFoundAt,
+            candidates: this.candidates.map((c) => c.url),
+            conflict: this.conflict,
+            via: this.via,
+            last_scan_at: this.lastScanAt ? new Date(this.lastScanAt).toISOString() : null,
+        };
+    }
+
+    stop() {
+        this.stopped = true;
+        clearTimeout(this.timer);
+    }
+}
+
+const httpAnswers = () => httpAnswered;
+
+module.exports = {Responder, Finder, probe, verify, scan, whoami, httpAnswers, sign, interfaces, settings};