@iola_adm/iola-cli 0.1.31 → 0.1.33

package/README.md

@@ -75,6 +75,7 @@ iola subagents list
 iola trajectory last
 iola review config
 iola browser status
+iola gosuslugi status
 ```
 
 Локальная модель через Ollama:
@@ -102,6 +103,7 @@ iola version --check
 - [Рабочая среда агента](https://github.com/adm-iola/iola-cli/wiki/Рабочая-среда-агента)
 - [Платформа агента](https://github.com/adm-iola/iola-cli/wiki/Платформа-агента)
 - [Браузерный агент](https://github.com/adm-iola/iola-cli/wiki/Браузерный-агент)
+- [Подключение Госуслуг](https://github.com/adm-iola/iola-cli/wiki/Подключение-Госуслуг)
 - [Расширения и локальные данные](https://github.com/adm-iola/iola-cli/wiki/Расширения-и-локальные-данные)
 - [Архивы и мастер настройки](https://github.com/adm-iola/iola-cli/wiki/Архивы-и-мастер-настройки)
 - [Daemon, RPC и cron](https://github.com/adm-iola/iola-cli/wiki/Daemon-RPC-и-cron)
@@ -119,6 +121,7 @@ iola version --check
 - subagents, skill bundles, layered settings, usage/budget accounting и trajectory export;
 - полноценный локальный MCP server по stdio/http: tools, resources и prompts;
 - браузерный runtime через Playwright: чтение страниц, скриншоты, PDF, клики, ввод и eval;
+- личное локальное подключение Госуслуг с явным согласием пользователя и хранением доступа только на его ПК;
 - управляемые локальные файловые операции с режимами `locked`, `read-only`, `workspace-write`, `full-access`;
 - планы выполнения, traces, tasks, artifacts, snapshots и policy-профили;
 - экспорт отчетов в Excel/Word-совместимые файлы;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iola_adm/iola-cli",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "CLI и AI-агент для работы с открытыми данными городского округа Йошкар-Ола.",
   "license": "MIT",
   "homepage": "https://github.com/adm-iola/iola-cli#readme",

package/src/cli.js

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { createServer } from "node:http";
 import { appendFile, copyFile, cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
@@ -30,6 +31,20 @@ const FILE_TOOLS = ["files_tree", "files_read", "files_search", "files_write", "
 const ALL_LOCAL_TOOLS = [...LOCAL_TOOLS, ...FILE_TOOLS];
 const HOOK_EVENTS = ["SessionStart", "BeforeTool", "AfterTool", "PreToolUse", "PostToolUse", "OnError", "AfterSync", "BeforeExport", "SessionEnd"];
 const DAEMON_PORT = Number(process.env.IOLA_DAEMON_PORT || 18790);
+const GOSUSLUGI_CONSENT_VERSION = "2026-05-26-personal-local-v1";
+const GOSUSLUGI_CONSENT_TEXT = `Подключение личных Госуслуг
+
+Вы подключаете личную учетную запись Госуслуг к локальному CLI-агенту iola-cli на этом компьютере.
+
+Нажимая "Да", вы подтверждаете, что:
+- используете собственную учетную запись Госуслуг;
+- понимаете, что все действия, выполненные через CLI-агента после подключения, считаются действиями владельца этой учетной записи;
+- разрешаете iola-cli локально сохранить данные доступа, необходимые для повторного входа или выполнения запросов от вашего имени;
+- понимаете, что данные доступа хранятся только на этом компьютере в локальном хранилище пользователя и не передаются разработчикам CLI, администрации города или третьим лицам;
+- обязуетесь не подключать чужие учетные записи и не передавать локальные файлы доступа другим лицам;
+- понимаете, что перед юридически значимыми действиями, отправкой заявлений, оплатой, подписанием или изменением персональных данных CLI должен запросить отдельное подтверждение.
+
+Продолжить подключение?`;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const BUILTIN_SKILLS_DIR = path.resolve(__dirname, "..", "skills");
 const USER_SKILLS_DIR = path.join(CONFIG_DIR, "skills");
@@ -109,6 +124,19 @@ const DEFAULT_AI_CONFIG = {
     baseUrl: "https://apiiola.yasg.ru/api/v1",
     mcpBaseUrl: "https://apiiola.yasg.ru",
   },
+  gosuslugi: {
+    enabled: false,
+    mode: "personal-local",
+    authUrl: "",
+    tokenUrl: "",
+    userinfoUrl: "",
+    clientId: "",
+    clientSecret: "",
+    scope: "openid",
+    redirectHost: "127.0.0.1",
+    redirectPort: 18791,
+    redirectPath: "/gosuslugi/callback",
+  },
   ai: {
     activeProfile: "local",
     provider: "ollama",
@@ -262,6 +290,7 @@ const COMMANDS = new Map([
   ["fork", forkSession],
   ["features", handleFeatures],
   ["settings", handleSettings],
+  ["gosuslugi", handleGosuslugi],
   ["wiki", handleWiki],
   ["context", handleContext],
   ["skills", handleSkills],
@@ -388,6 +417,7 @@ Usage:
   iola fork SESSION_ID [TEXT]
   iola features list|enable|disable
   iola settings list|get|validate|doctor|init
+  iola gosuslugi terms|consent|configure|status|login|logout|userinfo
   iola wiki [open|links]
   iola context list|show|init
   iola skills list|show|paths|enable|disable|bundles|bundle|doctor
@@ -684,6 +714,11 @@ async function handleAgentLine(line, state) {
     return false;
   }
 
+  if (command === "gosuslugi") {
+    await handleGosuslugi(args);
+    return false;
+  }
+
   if (command === "workspace") {
     await handleWorkspace(args);
     return false;
@@ -833,6 +868,7 @@ async function handleAgentLine(line, state) {
     resume: ["resume", args],
     fork: ["fork", args],
     features: ["features", args],
+    gosuslugi: ["gosuslugi", args],
     wiki: ["wiki", args],
     context: ["context", args],
     skills: ["skills", args],
@@ -891,6 +927,7 @@ function printAgentHelp() {
   /sessions
   /resume SESSION_ID
   /features list
+  /gosuslugi status
   /wiki
   /context list
   /skills list
@@ -1700,6 +1737,89 @@ async function handleSettings(args) {
   throw new Error("Команды settings: list, get [KEY], validate, doctor, init.");
 }
 
+async function handleGosuslugi(args) {
+  const [action = "status", ...rest] = args;
+  const options = parseOptions(rest);
+
+  if (action === "terms") {
+    console.log(GOSUSLUGI_CONSENT_TEXT);
+    return;
+  }
+
+  if (action === "consent") {
+    await acceptGosuslugiConsent(options);
+    return;
+  }
+
+  if (action === "status") {
+    const config = await loadConfig();
+    const secrets = await loadSecrets();
+    const tokens = secrets.gosuslugi?.tokens || null;
+    const consent = secrets.gosuslugiConsent || null;
+    printKeyValue({
+      mode: config.gosuslugi?.mode || "personal-local",
+      enabled: config.gosuslugi?.enabled ? "yes" : "no",
+      configured: isGosuslugiConfigured(config) ? "yes" : "no",
+      consent: consent?.version === GOSUSLUGI_CONSENT_VERSION ? "accepted" : "not accepted",
+      consentAt: consent?.acceptedAt || "-",
+      clientId: config.gosuslugi?.clientId ? maskSecret(config.gosuslugi.clientId) : "-",
+      authUrl: config.gosuslugi?.authUrl || "-",
+      tokenUrl: config.gosuslugi?.tokenUrl || "-",
+      userinfoUrl: config.gosuslugi?.userinfoUrl || "-",
+      redirectUri: gosuslugiRedirectUri(config),
+      connected: tokens?.access_token ? "yes" : "no",
+      savedAt: secrets.gosuslugi?.savedAt || "-",
+      expiresAt: secrets.gosuslugi?.expiresAt || "-",
+    });
+    return;
+  }
+
+  if (action === "configure") {
+    const current = await loadConfig();
+    const next = {
+      ...(current.gosuslugi || {}),
+      enabled: true,
+      mode: "personal-local",
+      authUrl: options["auth-url"] || current.gosuslugi?.authUrl || "",
+      tokenUrl: options["token-url"] || current.gosuslugi?.tokenUrl || "",
+      userinfoUrl: options["userinfo-url"] || current.gosuslugi?.userinfoUrl || "",
+      clientId: options["client-id"] || current.gosuslugi?.clientId || "",
+      clientSecret: options["client-secret"] || current.gosuslugi?.clientSecret || "",
+      scope: options.scope || current.gosuslugi?.scope || "openid",
+      redirectHost: options["redirect-host"] || current.gosuslugi?.redirectHost || "127.0.0.1",
+      redirectPort: Number(options["redirect-port"] || current.gosuslugi?.redirectPort || 18791),
+      redirectPath: options["redirect-path"] || current.gosuslugi?.redirectPath || "/gosuslugi/callback",
+    };
+    await saveConfig({ gosuslugi: next });
+    console.log("Настройки личного локального подключения Госуслуг сохранены.");
+    console.log(`Redirect URI: ${gosuslugiRedirectUri({ gosuslugi: next })}`);
+    return;
+  }
+
+  if (action === "login") {
+    const result = await gosuslugiLogin(options);
+    printKeyValue(result);
+    return;
+  }
+
+  if (action === "logout") {
+    const secrets = await loadSecrets();
+    delete secrets.gosuslugi;
+    await saveSecrets(secrets);
+    console.log("Локальное подключение Госуслуг удалено.");
+    return;
+  }
+
+  if (action === "userinfo" || action === "me") {
+    const result = await gosuslugiUserinfo(options);
+    if (options.json) printJson(result);
+    else printKeyValue(flattenObjectForPrint(result));
+    return;
+  }
+
+  throw new Error("Команды gosuslugi: terms, consent, configure, status, login, logout, userinfo.");
+}
+
 async function handleWiki(args) {
   const [action = "links"] = args;
   const base = "https://github.com/adm-iola/iola-cli/wiki";
@@ -1714,6 +1834,7 @@ async function handleWiki(args) {
     ["Рабочая среда агента", `${base}/Рабочая-среда-агента`],
     ["Платформа агента", `${base}/Платформа-агента`],
     ["Браузерный агент", `${base}/Браузерный-агент`],
+    ["Подключение Госуслуг", `${base}/Подключение-Госуслуг`],
     ["Расширения и локальные данные", `${base}/Расширения-и-локальные-данные`],
     ["Архивы и мастер настройки", `${base}/Архивы-и-мастер-настройки`],
     ["Daemon, RPC и cron", `${base}/Daemon-RPC-и-cron`],
@@ -2640,6 +2761,204 @@ async function openUrl(url) {
   await runCommand("xdg-open", [url], { inherit: false });
 }
 
+async function gosuslugiLogin(options = {}) {
+  const config = await loadConfig();
+  if (!isGosuslugiConfigured(config)) {
+    throw new Error("Личное подключение не настроено. Пример: iola gosuslugi configure --auth-url URL --token-url URL --client-id ID --scope openid");
+  }
+  await ensureGosuslugiConsent(options);
+
+  const state = randomUrlSafe(24);
+  const codeVerifier = randomUrlSafe(64);
+  const codeChallenge = base64Url(createHash("sha256").update(codeVerifier).digest());
+  const redirectUri = gosuslugiRedirectUri(config);
+  const callback = waitForOAuthCallback(config.gosuslugi, state, Number(options.timeout || 180000));
+  const authUrl = new URL(config.gosuslugi.authUrl);
+  authUrl.searchParams.set("response_type", "code");
+  authUrl.searchParams.set("client_id", config.gosuslugi.clientId);
+  authUrl.searchParams.set("redirect_uri", redirectUri);
+  authUrl.searchParams.set("scope", config.gosuslugi.scope || "openid");
+  authUrl.searchParams.set("state", state);
+  authUrl.searchParams.set("code_challenge", codeChallenge);
+  authUrl.searchParams.set("code_challenge_method", "S256");
+
+  console.log("Открываю экран входа Госуслуг в браузере для личного локального подключения.");
+  console.log("После входа CLI примет callback на локальном адресе и сохранит данные доступа только на этом компьютере.");
+  await openUrl(authUrl.toString());
+  const params = await callback;
+  if (params.error) throw new Error(`Госуслуги вернули ошибку: ${params.error} ${params.error_description || ""}`.trim());
+  if (!params.code) throw new Error("Authorization code не получен.");
+
+  const tokens = await exchangeGosuslugiCode(config, {
+    code: params.code,
+    codeVerifier,
+    redirectUri,
+  });
+  const secrets = await loadSecrets();
+  const now = new Date();
+  const expiresAt = tokens.expires_in ? new Date(now.getTime() + Number(tokens.expires_in) * 1000).toISOString() : "";
+  secrets.gosuslugi = {
+    savedAt: now.toISOString(),
+    expiresAt,
+    tokens,
+  };
+  await saveSecrets(secrets);
+  return {
+    connected: "yes",
+    savedAt: secrets.gosuslugi.savedAt,
+    expiresAt: expiresAt || "-",
+    tokenType: tokens.token_type || "-",
+    scope: tokens.scope || config.gosuslugi.scope || "-",
+  };
+}
+
+async function acceptGosuslugiConsent(options = {}) {
+  console.log(GOSUSLUGI_CONSENT_TEXT);
+  if (!options.yes) {
+    const accepted = await confirm("Да, подключить личные Госуслуги к локальному iola-cli? [y/N] ");
+    if (!accepted) {
+      throw new Error("Подключение Госуслуг отменено пользователем.");
+    }
+  }
+  const secrets = await loadSecrets();
+  secrets.gosuslugiConsent = {
+    version: GOSUSLUGI_CONSENT_VERSION,
+    acceptedAt: new Date().toISOString(),
+    user: os.userInfo().username,
+    host: os.hostname(),
+  };
+  await saveSecrets(secrets);
+  console.log("Согласие сохранено локально.");
+}
+
+async function ensureGosuslugiConsent(options = {}) {
+  const secrets = await loadSecrets();
+  if (secrets.gosuslugiConsent?.version === GOSUSLUGI_CONSENT_VERSION) return;
+  await acceptGosuslugiConsent(options);
+}
+
+function waitForOAuthCallback(settings, expectedState, timeoutMs) {
+  const host = settings.redirectHost || "127.0.0.1";
+  const port = Number(settings.redirectPort || 18791);
+  const callbackPath = settings.redirectPath || "/gosuslugi/callback";
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      server.close(() => {});
+      reject(new Error("Истекло время ожидания входа через Госуслуги."));
+    }, timeoutMs);
+    const server = createServer((req, res) => {
+      const url = new URL(req.url || "/", `http://${host}:${port}`);
+      if (url.pathname !== callbackPath) {
+        res.statusCode = 404;
+        res.end("Not found");
+        return;
+      }
+      const params = Object.fromEntries(url.searchParams.entries());
+      if (params.state !== expectedState) {
+        res.statusCode = 400;
+        res.end("Invalid state");
+        clearTimeout(timer);
+        server.close(() => {});
+        reject(new Error("OAuth state не совпал. Вход отменен."));
+        return;
+      }
+      res.setHeader("content-type", "text/html; charset=utf-8");
+      res.end("<!doctype html><meta charset=\"utf-8\"><title>iola</title><body>Вход выполнен. Можно закрыть это окно и вернуться в терминал.</body>");
+      clearTimeout(timer);
+      server.close(() => resolve(params));
+    });
+    server.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    server.listen(port, host);
+  });
+}
+
+async function exchangeGosuslugiCode(config, { code, codeVerifier, redirectUri }) {
+  const body = new URLSearchParams();
+  body.set("grant_type", "authorization_code");
+  body.set("code", code);
+  body.set("redirect_uri", redirectUri);
+  body.set("client_id", config.gosuslugi.clientId);
+  body.set("code_verifier", codeVerifier);
+  body.set("client_mode", config.gosuslugi.mode || "personal-local");
+  if (config.gosuslugi.clientSecret) body.set("client_secret", config.gosuslugi.clientSecret);
+
+  const response = await fetch(config.gosuslugi.tokenUrl, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body,
+  });
+  const text = await response.text();
+  let payload = {};
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    payload = { raw: text };
+  }
+  if (!response.ok) {
+    throw new Error(`Token endpoint вернул ${response.status}: ${JSON.stringify(payload)}`);
+  }
+  return payload;
+}
+
+async function gosuslugiUserinfo() {
+  const config = await loadConfig();
+  const secrets = await loadSecrets();
+  const accessToken = secrets.gosuslugi?.tokens?.access_token;
+  if (!accessToken) throw new Error("Госуслуги не подключены. Запустите: iola gosuslugi login");
+  if (!config.gosuslugi?.userinfoUrl) throw new Error("userinfoUrl не настроен.");
+  const response = await fetch(config.gosuslugi.userinfoUrl, {
+    headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+  });
+  const text = await response.text();
+  let payload = {};
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    payload = { raw: text };
+  }
+  if (!response.ok) throw new Error(`Userinfo endpoint вернул ${response.status}: ${JSON.stringify(payload)}`);
+  return payload;
+}
+
+function isGosuslugiConfigured(config) {
+  return Boolean(config.gosuslugi?.authUrl && config.gosuslugi?.tokenUrl && config.gosuslugi?.clientId);
+}
+
+function gosuslugiRedirectUri(config) {
+  const settings = config.gosuslugi || DEFAULT_AI_CONFIG.gosuslugi;
+  return `http://${settings.redirectHost || "127.0.0.1"}:${Number(settings.redirectPort || 18791)}${settings.redirectPath || "/gosuslugi/callback"}`;
+}
+
+function randomUrlSafe(bytes) {
+  return base64Url(randomBytes(bytes));
+}
+
+function base64Url(buffer) {
+  return Buffer.from(buffer).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function maskSecret(value) {
+  const text = String(value || "");
+  if (text.length <= 8) return text ? "***" : "-";
+  return `${text.slice(0, 4)}...${text.slice(-4)}`;
+}
+
+function flattenObjectForPrint(value, prefix = "") {
+  const rows = {};
+  for (const [key, item] of Object.entries(value || {})) {
+    const name = prefix ? `${prefix}.${key}` : key;
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+      Object.assign(rows, flattenObjectForPrint(item, name));
+    } else {
+      rows[name] = Array.isArray(item) ? item.join(", ") : item;
+    }
+  }
+  return rows;
+}
+
 async function handlePermissions(args) {
   const [action = "list", name] = args;
   const config = await loadConfig();
@@ -6001,7 +6320,7 @@ function parseOptions(args) {
     } else if (arg === "--check" || arg === "--upgrade-node") {
       result.check = true;
       result[arg.slice(2)] = true;
-    } else if (arg === "--limit" || arg === "--offset" || arg === "--search" || arg === "--replace" || arg === "--text" || arg === "--path" || arg === "--depth" || arg === "--max-bytes" || arg === "--query" || arg === "--where" || arg === "--columns" || arg === "--inn" || arg === "--model" || arg === "--provider" || arg === "--profile" || arg === "--name" || arg === "--source" || arg === "--command" || arg === "--prompt" || arg === "--description" || arg === "--base-url" || arg === "--sandbox" || arg === "--approval" || arg === "--cwd" || arg === "--codex-profile" || arg === "--format" || arg === "--output" || arg === "--schema" || arg === "--session" || arg === "--temperature" || arg === "--config" || arg === "--dataset" || arg === "--save" || arg === "--reasoning" || arg === "--agent" || arg === "--scope" || arg === "--selector" || arg === "--url" || arg === "--timeout" || arg === "--wait" || arg === "--viewport" || arg === "--press" || arg === "--script" || arg === "--debug-file") {
+    } else if (arg === "--limit" || arg === "--offset" || arg === "--search" || arg === "--replace" || arg === "--text" || arg === "--path" || arg === "--depth" || arg === "--max-bytes" || arg === "--query" || arg === "--where" || arg === "--columns" || arg === "--inn" || arg === "--model" || arg === "--provider" || arg === "--profile" || arg === "--name" || arg === "--source" || arg === "--command" || arg === "--prompt" || arg === "--description" || arg === "--base-url" || arg === "--sandbox" || arg === "--approval" || arg === "--cwd" || arg === "--codex-profile" || arg === "--format" || arg === "--output" || arg === "--schema" || arg === "--session" || arg === "--temperature" || arg === "--config" || arg === "--dataset" || arg === "--save" || arg === "--reasoning" || arg === "--agent" || arg === "--scope" || arg === "--selector" || arg === "--url" || arg === "--timeout" || arg === "--wait" || arg === "--viewport" || arg === "--press" || arg === "--script" || arg === "--auth-url" || arg === "--token-url" || arg === "--userinfo-url" || arg === "--client-id" || arg === "--client-secret" || arg === "--redirect-host" || arg === "--redirect-port" || arg === "--redirect-path" || arg === "--debug-file") {
       result[arg.slice(2)] = args[index + 1];
       index += 1;
     } else {
@@ -7769,6 +8088,10 @@ function mergeConfig(base, override) {
       ...base.api,
       ...(override.api || {}),
     },
+    gosuslugi: {
+      ...base.gosuslugi,
+      ...(override.gosuslugi || {}),
+    },
     ai: {
       ...base.ai,
       ...(override.ai || {}),
@@ -7843,6 +8166,9 @@ function validateConfig(config) {
   for (const toolset of config.toolsets?.enabled || []) {
     if (!TOOLSETS[toolset]) errors.push(`toolsets.enabled содержит неизвестный toolset: ${toolset}`);
   }
+  if (config.gosuslugi?.enabled && !isGosuslugiConfigured(config)) {
+    errors.push("gosuslugi включен, но authUrl/tokenUrl/clientId не заполнены");
+  }
   return errors;
 }
 
@@ -7852,6 +8178,7 @@ function configSchema() {
     required: ["api", "ai"],
     properties: {
       api: { required: ["baseUrl", "mcpBaseUrl"] },
+      gosuslugi: { requiredWhenEnabled: ["authUrl", "tokenUrl", "clientId"], optional: ["userinfoUrl", "clientSecret", "scope", "redirectHost", "redirectPort", "redirectPath"] },
       ai: { required: ["activeProfile", "profiles"], providers: ["ollama", "openai", "openrouter", "codex"] },
       permissions: { localTools: ALL_LOCAL_TOOLS, runtime: ["readFiles", "writeFiles", "editFiles", "deleteFiles", "sync", "externalApi", "externalAi", "codex"] },
       toolsets: { available: Object.keys(TOOLSETS) },

package/wiki/Home.md

@@ -33,6 +33,7 @@ iola ask "найди школу 29"
 - [Рабочая среда агента](Рабочая-среда-агента)
 - [Платформа агента](Платформа-агента)
 - [Браузерный агент](Браузерный-агент)
+- [Подключение Госуслуг](Подключение-Госуслуг)
 - [Расширения и локальные данные](Расширения-и-локальные-данные)
 - [Архивы и мастер настройки](Архивы-и-мастер-настройки)
 - [Daemon, RPC и cron](Daemon-RPC-и-cron)

package/wiki//320/232/320/276/320/274/320/260/320/275/320/264/321/213.md

@@ -92,6 +92,12 @@ iola context init
 iola context list
 iola settings list
 iola settings validate
+iola gosuslugi status
+iola gosuslugi terms
+iola gosuslugi consent
+iola gosuslugi configure --auth-url URL --token-url URL --client-id ID --scope openid
+iola gosuslugi login
+iola gosuslugi userinfo --json
 iola cron add "каждый день 09:00 -- quality"
 iola cron tick
 iola daemon status

package/wiki//320/237/320/276/320/264/320/272/320/273/321/216/321/207/320/265/320/275/320/270/320/265-/320/223/320/276/321/201/321/203/321/201/320/273/321/203/320/263.md

@@ -0,0 +1,101 @@
+# Личное подключение Госуслуг
+
+`iola-cli` поддерживает локальное подключение личной учетной записи Госуслуг на компьютере пользователя.
+
+Сценарий рассчитан именно на пользователя, который ставит CLI на свой ПК и подключает свою учетную запись. Ключи организации или администрации в публичный пакет не вшиваются.
+
+## Согласие пользователя
+
+Перед входом CLI показывает текст согласия:
+
+```text
+Вы подключаете личную учетную запись Госуслуг к локальному CLI-агенту iola-cli на этом компьютере.
+
+Нажимая "Да", вы подтверждаете, что:
+- используете собственную учетную запись Госуслуг;
+- понимаете, что все действия, выполненные через CLI-агента после подключения, считаются действиями владельца этой учетной записи;
+- разрешаете iola-cli локально сохранить данные доступа, необходимые для повторного входа или выполнения запросов от вашего имени;
+- понимаете, что данные доступа хранятся только на этом компьютере в локальном хранилище пользователя и не передаются разработчикам CLI, администрации города или третьим лицам;
+- обязуетесь не подключать чужие учетные записи и не передавать локальные файлы доступа другим лицам;
+- понимаете, что перед юридически значимыми действиями, отправкой заявлений, оплатой, подписанием или изменением персональных данных CLI должен запросить отдельное подтверждение.
+```
+
+Посмотреть текст:
+
+```bash
+iola gosuslugi terms
+```
+
+Принять заранее:
+
+```bash
+iola gosuslugi consent
+```
+
+## Настройка
+
+Для работы нужны параметры пользовательского OAuth/OIDC-подключения:
+
+- authorization endpoint;
+- token endpoint;
+- client ID;
+- разрешенный redirect URI;
+- scope;
+- optional client secret, если он выдан именно пользователю или локальному приложению;
+- optional userinfo endpoint.
+
+Команда настройки:
+
+```bash
+iola gosuslugi configure \
+  --auth-url "https://..." \
+  --token-url "https://..." \
+  --userinfo-url "https://..." \
+  --client-id "CLIENT_ID" \
+  --scope "openid" \
+  --redirect-port 18791
+```
+
+CLI покажет redirect URI:
+
+```text
+http://127.0.0.1:18791/gosuslugi/callback
+```
+
+Этот URI должен быть разрешен в настройках подключения.
+
+## Вход
+
+```bash
+iola gosuslugi login
+```
+
+Что происходит:
+
+1. CLI запускает локальный callback server на `127.0.0.1`.
+2. Показывается и сохраняется согласие пользователя.
+3. Открывается экран входа Госуслуг.
+4. Пользователь сам вводит логин, пароль, SMS/2FA.
+5. Госуслуги возвращают `authorization code` на локальный callback.
+6. CLI обменивает code на токены и сохраняет их локально.
+
+Токены хранятся в `~/.iola/secrets.json` на компьютере пользователя.
+
+## Проверка
+
+```bash
+iola gosuslugi status
+iola gosuslugi userinfo --json
+```
+
+## Выход
+
+```bash
+iola gosuslugi logout
+```
+
+Команда удаляет локально сохраненные токены.
+
+## Ограничения
+
+Без параметров пользовательского подключения команда `login` не сможет завершить подключение. Все ключи, токены и настройки хранятся только локально у пользователя.