@nnsi/sdk-electron 0.1.0

package/README.md

@@ -0,0 +1,432 @@
+# @nnsi/sdk-electron
+
+Официальный SDK для Windows-приложений на Electron, которые распространяются и запускаются через **NNSI App**.
+
+SDK проверяет короткоживущий подписанный `launch ticket`. Лаунчер получает ticket после проверки пользователя и лицензии в Supabase, а приложение проверяет его локально по публичному RSA-ключу.
+
+> Важно: SDK не заменяет code signing, DRM и серверную авторизацию критичных операций. Клиентское приложение работает на компьютере пользователя, поэтому особо важную логику не следует полностью доверять клиенту.
+
+## Архитектура
+
+```text
+Вход в NNSI App
+  -> Edge Function получает access token, app_id, machine_id
+  -> проверяет app_licenses
+  -> подписывает RS256 launch ticket
+  -> лаунчер передаёт ticket приложению через environment
+  -> приложение проверяет ticket через SDK
+```
+
+Приватный RSA-ключ хранится только в Edge Function. В приложении и лаунчере находится только public key: им можно проверять подпись, но нельзя выпускать tickets.
+
+## Установка
+
+Для локальной разработки добавьте в `package.json` приложения:
+
+```json
+{
+  "dependencies": {
+    "@nnsi/sdk-electron": "file:../sdk-electron"
+  }
+}
+```
+
+Путь считается относительно `package.json`. Затем:
+
+```powershell
+npm install
+```
+
+После публикации в npm-реестре:
+
+```powershell
+npm install @nnsi/sdk-electron
+```
+
+В production фиксируйте точную версию пакета.
+
+## Быстрое подключение
+
+Проверку нужно выполнять в главном процессе Electron, до создания основных окон:
+
+```js
+const { app, dialog } = require('electron');
+const { requireLauncher } = require('@nnsi/sdk-electron');
+
+let nnsiContext;
+try {
+  nnsiContext = requireLauncher({
+    appId: 'myapp',
+    publicKey: process.env.NNSI_TICKET_PUBLIC_KEY
+  });
+} catch (error) {
+  dialog.showErrorBox(
+    'My App',
+    error instanceof Error ? error.message : 'Запуск через NNSI App не подтверждён.'
+  );
+  app.quit();
+  return;
+}
+
+console.log('NNSI user:', nnsiContext.user_id);
+// Только после этого создаём BrowserWindow.
+```
+
+Проверки только в renderer недостаточно: основной процесс должен завершиться до создания интерфейса.
+
+## API
+
+```js
+const {
+  requireLauncher,
+  getLaunchContext,
+  verifyTicket
+} = require('@nnsi/sdk-electron');
+```
+
+### `requireLauncher(options)`
+
+Читает ticket из environment и проверяет его. При ошибке выбрасывает `Error`.
+
+```js
+const context = requireLauncher({
+  appId: 'tiktimer',
+  publicKey: process.env.NNSI_TICKET_PUBLIC_KEY
+});
+```
+
+Параметры:
+
+| Параметр | Тип | Назначение |
+|---|---|---|
+| `appId` | string | ID приложения; ticket другого приложения будет отклонён |
+| `publicKey` | string | RSA public key в PEM-формате |
+| `issuer` | string | Издатель; по умолчанию `nnsi-app` |
+| `ticketEnv` | string | Имя переменной ticket; по умолчанию `NNSI_LAUNCH_TICKET` |
+
+### `getLaunchContext(options)`
+
+Псевдоним `requireLauncher`, возвращает payload проверенного ticket:
+
+```js
+const context = getLaunchContext({
+  appId: 'myapp',
+  publicKey: PUBLIC_KEY
+});
+```
+
+### `verifyTicket(ticket, options)`
+
+Проверяет уже прочитанную JWT-строку. Полезно для тестов:
+
+```js
+const context = verifyTicket(ticket, {
+  appId: 'myapp',
+  publicKey: PUBLIC_KEY
+});
+```
+
+Проверяются формат JWT, алгоритм `RS256`, подпись RSA-SHA256, `iss`, `app_id`, `exp` и `nbf`. Payload возвращается замороженным через `Object.freeze()`.
+
+## Environment-переменные
+
+Лаунчер передаёт:
+
+| Переменная | Значение |
+|---|---|
+| `NNSI_LAUNCH_TICKET` | Подписанный короткоживущий JWT |
+| `NNSI_TICKET_PUBLIC_KEY` | Публичный RSA-ключ в PEM |
+
+Для локального теста:
+
+```powershell
+$env:NNSI_LAUNCH_TICKET = 'test-ticket'
+$env:NNSI_TICKET_PUBLIC_KEY = (Get-Content .\keys\nnsi-public.pem -Raw)
+npm start
+```
+
+Не храните production ticket, private key или service role key в `.env`, Git, EXE или ZIP.
+
+## Формат launch ticket
+
+Ticket — JWT с подписью `RS256`:
+
+```json
+{
+  "iss": "nnsi-app",
+  "sub": "supabase-user-uuid",
+  "user_id": "supabase-user-uuid",
+  "app_id": "tiktimer",
+  "machine_id": "stable-machine-id",
+  "jti": "unique-ticket-id",
+  "iat": 1770000000,
+  "nbf": 1769999995,
+  "exp": 1770000300
+}
+```
+
+- `iss` — издатель;
+- `sub`, `user_id` — пользователь Supabase;
+- `app_id` — разрешённое приложение;
+- `machine_id` — компьютер лицензии;
+- `jti` — уникальный ticket;
+- `iat`, `nbf`, `exp` — времена выпуска, начала и окончания действия в Unix seconds.
+
+Текущая Edge Function выдаёт ticket на 5 минут. Перед каждым запуском лаунчер должен получать новый ticket.
+
+## Генерация RSA-ключей
+
+```powershell
+New-Item -ItemType Directory -Force .\keys | Out-Null
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out .\keys\nnsi-private.pem
+openssl rsa -pubout -in .\keys\nnsi-private.pem -out .\keys\nnsi-public.pem
+```
+
+Private key должен начинаться с:
+
+```text
+-----BEGIN PRIVATE KEY-----
+```
+
+Добавьте в `.gitignore`:
+
+```gitignore
+keys/
+*.pem
+.env
+```
+
+## Supabase Edge Function
+
+Функция находится в:
+
+```text
+supabase/functions/issue-launch-ticket/index.ts
+```
+
+Она:
+
+1. принимает Bearer access token;
+2. получает пользователя через `auth.getUser()`;
+3. принимает `app_id` и `machine_id`;
+4. ищет активную запись `public.app_licenses`;
+5. проверяет `expires_at`;
+6. подписывает ticket;
+7. пишет аудит в `public.license_launches`;
+8. возвращает ticket.
+
+Тело запроса:
+
+```json
+{
+  "app_id": "tiktimer",
+  "machine_id": "computer-identifier"
+}
+```
+
+Успех:
+
+```json
+{
+  "ticket": "eyJ...",
+  "expires_at": "2026-09-05T12:00:00.000Z"
+}
+```
+
+Если лицензия не найдена, функция возвращает HTTP 403.
+
+### Схема и лицензия
+
+Выполните актуальный `launcher/supabase-schema.sql`. Для теста добавьте лицензию:
+
+```sql
+insert into public.app_licenses
+  (user_id, app_id, machine_id, is_active, expires_at)
+values
+  ('USER_UUID', 'tiktimer', 'computer-identifier', true, null);
+```
+
+`user_id` должен быть UUID текущего пользователя, а `machine_id` — тем же значением, которое отправляет лаунчер.
+
+### Deploy и secrets
+
+```powershell
+supabase login
+supabase link --project-ref YOUR_PROJECT_REF
+supabase secrets set SUPABASE_SERVICE_ROLE_KEY="YOUR_SERVICE_ROLE_KEY"
+supabase secrets set NNSI_TICKET_PRIVATE_KEY="YOUR_PRIVATE_RSA_PEM"
+supabase functions deploy issue-launch-ticket
+```
+
+Private key и service role key задаются только как secrets Edge Function. Если CLI некорректно передаёт многострочный PEM, задайте его через Supabase Dashboard.
+
+## Подключение лаунчера
+
+Лаунчер вызывает Edge Function с access token текущей Supabase-сессии:
+
+```js
+async function issueLaunchTicket({ supabaseUrl, anonKey, accessToken, appId, machineId }) {
+  const response = await fetch(
+    `${supabaseUrl}/functions/v1/issue-launch-ticket`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        apikey: anonKey,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ app_id: appId, machine_id: machineId })
+    }
+  );
+
+  const data = await response.json();
+  if (!response.ok) throw new Error(data.error || `Ticket request failed: ${response.status}`);
+  return data;
+}
+```
+
+Запуск дочернего процесса:
+
+```js
+const childEnv = {
+  ...process.env,
+  NNSI_LAUNCH_TICKET: ticket,
+  NNSI_TICKET_PUBLIC_KEY: publicKey
+};
+
+delete childEnv.ELECTRON_RUN_AS_NODE;
+
+spawn(executablePath, [], {
+  cwd: appDirectory,
+  env: childEnv,
+  windowsHide: false
+});
+```
+
+Public key лучше хранить в самом лаунчере или подписанной конфигурации, а не брать из непроверенного каталога приложения.
+
+## Модель лицензий
+
+Пользователь не должен иметь публичные INSERT/UPDATE policies на `app_licenses`. Иначе он сможет выдать себе лицензию.
+
+Рекомендуется:
+
+- публичный доступ только к опубликованному каталогу;
+- чтение лицензии через Edge Function с service role;
+- изменение `is_active`, `expires_at`, `app_id` и `machine_id` только через админ-панель или защищённую серверную функцию;
+- аудит запусков в `license_launches`.
+
+Старую клиентскую логику TikTimer, которая напрямую читает или меняет `app_licenses`, нужно заменить серверным API. Не ослабляйте RLS ради совместимости.
+
+## Пример для TikTimer
+
+```js
+const { app, dialog } = require('electron');
+const { getLaunchContext } = require('@nnsi/sdk-electron');
+
+let nnsiContext;
+try {
+  nnsiContext = getLaunchContext({
+    appId: 'tiktimer',
+    publicKey: process.env.NNSI_TICKET_PUBLIC_KEY
+  });
+} catch (error) {
+  dialog.showErrorBox(
+    'TikTimer',
+    'TikTimer можно запустить только через NNSI App.\n\n' +
+      (error instanceof Error ? error.message : 'Проверка не пройдена.')
+  );
+  app.quit();
+  return;
+}
+
+console.log('Authorized user:', nnsiContext.user_id);
+// Создание BrowserWindow только здесь, после проверки.
+```
+
+После добавления зависимости:
+
+```powershell
+npm install
+npm run build
+```
+
+Проверьте, что SDK попал в `resources/app.asar` и включён в `build.files`.
+
+## Тестовый чек-лист
+
+Проверьте все сценарии:
+
+1. Запуск EXE напрямую без env — отказ и отсутствие главного окна.
+2. Запуск через лаунчер с активной лицензией — успех.
+3. Неверная пара RSA-ключей — отказ.
+4. Ticket с другим `app_id` — отказ.
+5. Просроченный ticket — отказ.
+6. Удалённая или истёкшая лицензия — Edge Function возвращает 403.
+7. Перезапуск после истечения ticket — лаунчер получает новый ticket.
+8. Сборка на чистом ПК — модуль SDK находится внутри приложения.
+
+## Ошибки
+
+| Сообщение | Причина |
+|---|---|
+| `This application can only be launched through NNSI App` | Нет `NNSI_LAUNCH_TICKET` |
+| `NNSI ticket public key is not configured` | Не передан public key |
+| `Invalid NNSI launch ticket signature` | Public key не соответствует private key или ticket повреждён |
+| `NNSI ticket belongs to another application` | Не совпали `appId` и `app_id` |
+| `NNSI launch ticket has expired` | Нужно запросить новый ticket |
+| `Active license not found` | Неверны user, app, machine или состояние лицензии |
+| `Cannot find module '@nnsi/sdk-electron'` | SDK не установлен или не попал в сборку |
+
+В логах не записывайте полный ticket:
+
+```js
+console.log({
+  hasTicket: Boolean(process.env.NNSI_LAUNCH_TICKET),
+  hasPublicKey: Boolean(process.env.NNSI_TICKET_PUBLIC_KEY)
+});
+```
+
+## Безопасность
+
+1. Никогда не помещайте private key и service role key в Electron, GitHub, EXE, ZIP или renderer.
+2. Используйте HTTPS и актуальный Electron.
+3. Выдавайте короткоживущий ticket перед каждым запуском.
+4. Проверяйте `app_id` и на сервере, и в приложении.
+5. Подписывайте Windows-сборки code-signing сертификатом.
+6. После утечки private key создайте новую RSA-пару, смените secret и выпустите приложения с новым public key.
+7. Ранее опубликованные Supabase secret/service-role ключи считайте скомпрометированными и ротируйте.
+
+SDK не может сделать локальный EXE абсолютно не взламываемым: пользователь контролирует файлы на своём компьютере. Его задача — связать официальный запуск с серверной лицензией и повысить стоимость обхода.
+
+## Публикация SDK
+
+Перед публикацией:
+
+```powershell
+node --check .\sdk-electron\index.js
+node -e "require('./sdk-electron')"
+```
+
+Увеличьте `version` в `sdk-electron/package.json`, затем:
+
+```powershell
+cd sdk-electron
+npm publish --access restricted
+```
+
+В приложении зафиксируйте новую версию и обновите lock-файл:
+
+```powershell
+npm install
+```
+
+## Файлы проекта
+
+```text
+sdk-electron/index.js                              SDK и проверка RS256
+sdk-electron/package.json                          метаданные npm-пакета
+supabase/functions/issue-launch-ticket/index.ts    выдача tickets
+launcher/supabase-schema.sql                       таблицы лицензий и аудита
+```
+

package/index.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const crypto = require('crypto');
+
+function decodeBase64Url(value) {
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(value.length / 4) * 4, '=');
+  return Buffer.from(normalized, 'base64');
+}
+
+function readJsonPart(value) {
+  return JSON.parse(decodeBase64Url(value).toString('utf8'));
+}
+
+function verifyTicket(ticket, options) {
+  if (typeof ticket !== 'string' || ticket.split('.').length !== 3) throw new Error('NNSI launch ticket is missing or malformed');
+  const [encodedHeader, encodedPayload, encodedSignature] = ticket.split('.');
+  const header = readJsonPart(encodedHeader);
+  const payload = readJsonPart(encodedPayload);
+  if (header.alg !== 'RS256') throw new Error('Unsupported NNSI ticket algorithm');
+  if (!options.publicKey) throw new Error('NNSI ticket public key is not configured');
+  const valid = crypto.verify('RSA-SHA256', Buffer.from(`${encodedHeader}.${encodedPayload}`), options.publicKey, decodeBase64Url(encodedSignature));
+  if (!valid) throw new Error('Invalid NNSI launch ticket signature');
+  const now = Math.floor(Date.now() / 1000);
+  if (payload.iss !== (options.issuer || 'nnsi-app')) throw new Error('Invalid NNSI ticket issuer');
+  if (options.appId && payload.app_id !== options.appId) throw new Error('NNSI ticket belongs to another application');
+  if (!payload.exp || payload.exp <= now) throw new Error('NNSI launch ticket has expired');
+  if (payload.nbf && payload.nbf > now + 30) throw new Error('NNSI launch ticket is not active yet');
+  return Object.freeze(payload);
+}
+
+function requireLauncher(options = {}) {
+  const ticket = process.env[options.ticketEnv || 'NNSI_LAUNCH_TICKET'];
+  if (!ticket) throw new Error('This application can only be launched through NNSI App');
+  return verifyTicket(ticket, options);
+}
+
+function getLaunchContext(options = {}) {
+  return requireLauncher(options);
+}
+
+module.exports = { requireLauncher, getLaunchContext, verifyTicket };

package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@nnsi/sdk-electron",
+  "version": "0.1.0",
+  "description": "Official SDK for applications launched by NNSI App",
+  "main": "index.js",
+  "type": "commonjs",
+  "license": "UNLICENSED",
+  "engines": { "node": ">=18" }
+}