@torrow/sdk-auth 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,438 @@
-# Temporary Holding Version
+# `@torrow/sdk-auth`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Сессия токенов поверх **`@torrow/sdk-client`**: storage, проактивный refresh, single-flight, **`refreshOnUnauthorized`** (default **true**), фасад **`TorrowAuth`**.
+
+В snapshot файла/storage: access / refresh / срок access / **`deviceId`**. Тип устройства (`deviceType`) задаёт приложение — в snapshot не пишется.
+
+IMAP / stdin / captcha-UI / чтение `process.env` — **не** в пакете (слой app / **`examples/node/_shared`**).
+
+## Выбор режима
+
+```mermaid
+flowchart TD
+  need[Нужен клиент] --> kind{Сценарий}
+  kind -->|restore| connect["TorrowAuth.connect"]
+  kind -->|OTP login| login["TorrowAuth.loginWithOtp"]
+  kind -->|раздельные OTP-запросы| flow["TorrowAuth.createOtpFlow: start / complete"]
+  kind -->|Telegram deep-link| link["TorrowAuth.loginWithLink"]
+  kind -->|токены от хоста| fromTok["TorrowAuth.fromTokens"]
+  kind -->|без входа| anon["TorrowAuth.anonymous"]
+  connect --> handle["TorrowAuthResult: client + session"]
+  login --> handle
+  link --> handle
+  fromTok --> handle
+  anon --> clientOnly["TorrowClient"]
+```
+
+Флоу / подсистема для агентов: **`docs/agents/auth-flow.md`**. Индекс примеров Node: **`examples/node/auth/README.md`**, **`examples/node/_shared/README.md`**.
+
+## Целевой клиентский код
+
+### Пошаговый OTP без пользовательской сессии
+
+`TorrowAuth.createOtpFlow` выполняет один `sendCode` на start и один `requestToken` на complete. Он не хранит challenge или токены, не требует TokenStorage/callbacks, не делает polling, refresh, retry или revoke. Для полного входа с callbacks и сохранением используйте `loginWithOtp`.
+
+```mermaid
+sequenceDiagram
+  actor User as Пользователь
+  participant App as Приложение
+  participant Flow as OtpFlow (@torrow/sdk-auth)
+  participant API as Torrow API
+
+  App->>Flow: createOtpFlow(options)
+  App->>Flow: start({ account, ... }, { signal })
+  Flow->>API: POST /auth/sendcode (Basic приложения)
+  API-->>Flow: SendCodeResp
+  Flow-->>App: OtpChallenge
+  Note over App,Flow: Classic — AwaitingCode, Mobile ID — Pending.<br/>Challenge не содержит токенов или OTP.
+  App->>App: Защитить и перенести challenge через JSON
+  Note over App,Flow: complete можно вызвать на новом экземпляре flow.<br/>deviceInfo, scopes и splitTokens сохраняет приложение.
+
+  loop Пока нет TokenReady / Failed и challenge не просрочен
+    alt challenge.phase = AwaitingCode
+      App->>User: Запросить OTP / SMS-код
+      User-->>App: code
+      App->>Flow: complete({ challenge, code }, { signal })
+    else challenge.phase = Pending
+      App->>App: При повторном polling дождаться интервала
+      App->>Flow: complete({ challenge }, { signal })
+    end
+    Note right of Flow: Проверить challenge до HTTP.<br/>Pending — wire code пустой.
+    Flow->>API: POST /auth/token (Basic приложения)
+    API-->>Flow: TokenResp
+    alt status = Pending
+      Flow-->>App: Pending + challenge (phase = Pending)<br/>+ cleanup, если есть refresh
+    else status = AwaitingSmsCode
+      Flow-->>App: SMS fallback той же Mobile ID сессии<br/>AwaitingSmsCode + challenge<br/>(новая phase = AwaitingCode, usedMethod = Sms)<br/>+ cleanup, если есть refresh
+    else status = TokenReady
+      Flow-->>App: TokenReady + tokens
+      App->>App: Использовать токены и решить вопрос хранения / cleanup
+    else status = Failed
+      Flow-->>App: Failed + cleanup, если есть refresh
+    end
+  end
+
+  Note over App,Flow: expiresAtMs не продлевается между шагами.<br/>Ошибки передаются приложению, скрытых повторов нет.<br/>Cleanup выполняет приложение с независимым AbortSignal.
+```
+
+```ts
+import { TorrowAuth, OtpFlowError, type OtpChallenge } from "@torrow/sdk-auth";
+import { TokenStatusValues } from "@torrow/sdk-client";
+
+const options = {
+  deviceInfo: { deviceId: "my-app-device", deviceType: "Desktop" as const },
+  scopes: ["user_api" as const],
+  splitTokens: false,
+};
+const challenge = await TorrowAuth.createOtpFlow(options).start({
+  account: { accountType: "Email", accountName: "user@example.com" },
+});
+// Между запросами приложение защищает целостность этого JSON.
+const continuation: OtpChallenge = JSON.parse(JSON.stringify(challenge));
+try {
+  const result = await TorrowAuth.createOtpFlow(options).complete(
+    { challenge: continuation, code: "123456" },
+    { signal: AbortSignal.timeout(15000) },
+  );
+  if (result.status === TokenStatusValues.TokenReady) {
+    // Использовать result.tokens.accessToken в рамках текущего запроса.
+    // Сохранение/cleanup result.tokens.refreshToken определяет приложение.
+  } else {
+    // result.cleanup?.refreshToken доступен для отдельного cleanup.
+    if ("challenge" in result) {
+      // Защитить result.challenge для следующего шага.
+    }
+  }
+} catch (error) {
+  if (error instanceof OtpFlowError) {
+    // error.code — безопасная причина; error.cleanup?.refreshToken — секрет для cleanup.
+    // Cleanup выполняет приложение с независимым AbortSignal.
+  }
+  throw error;
+}
+```
+
+| Значение | Действие приложения |
+|---|---|
+| `challenge.phase: AwaitingCode` | Для следующего шага требуется непустой код. Это первоначальный ввод при обычном OTP либо ввод SMS-кода после fallback в Mobile ID-сценарии. |
+| `challenge.phase: Pending` | Продолжается ожидание результата Mobile ID. Следующий complete вызывается без кода; wire code будет пустым. |
+| `result.status: Pending` | Сервер ещё не завершил аутентификацию. SDK возвращает challenge с фазой Pending; приложение планирует следующий запрос без кода. Возможен возврат к Pending после отправки SMS-кода. |
+| `result.status: AwaitingSmsCode` | Сервер перевёл Mobile ID-сценарий на SMS fallback, поскольку аутентификацию через Mobile ID не удалось завершить. SDK возвращает challenge с новой фазой AwaitingCode и методом Sms; приложение запрашивает SMS-код и передаёт его в следующий complete. |
+| `result.status: Failed` | Текущая попытка аутентификации завершилась отказом. Challenge для продолжения не возвращается; новый вход требует отдельного start. |
+| `result.status: TokenReady` | Аутентификация завершена, токены получены и проверены SDK. Продолжение не требуется; SDK не сохраняет токены. |
+
+`result.status` отражает серверный `TokenStatus`, а `challenge.phase` определяет следующий шаг приложения. Переход при fallback: ожидание Mobile ID (`Pending`) → серверный `AwaitingSmsCode` → ввод SMS-кода (новая фаза `AwaitingCode`, метод `Sms`). Это продолжение той же auth-сессии с новым способом подтверждения, а не продолжение фазы AwaitingCode: sessionId и deadline сохраняются, фаза меняется. При обычном Email/SMS/FlashCall/TelegramGateway-входе `start` сразу возвращает `AwaitingCode` с фактическим `usedMethod`: ввод кода требуется до первого `complete`. Статуса `AwaitingEmailCode` в текущем API нет. Предпочтительный метод `preferredMethod` является пожеланием; фактический метод определяет сервер в `usedMethod`.
+
+Опции flow: `baseUrl`, `fetch`, `defaultHeaders`, `userAgent`, `appCredentials`, обязательный `deviceInfo`, `scopes`, `splitTokens`. SDK-default Basic и scopes такие же, как в сессии; неуказанный splitTokens не отправляется. Start принимает язык (default ru), регион (70), captcha/type, invite session и preferred/supported methods. Email/UnknownMethod поддерживается; неизвестный метод отклоняется.
+
+**Когда использовать `splitTokens`.** Это параметр `POST /api/v1/auth/token`, который обрабатывает сервер: SDK передаёт флаг и возвращает полученные поля токенов без самостоятельного разделения или восстановления.
+
+| Значение | Поведение сервера и сценарий |
+|---|---|
+| `false` | Возвращает полные access/refresh в JSON и удаляет cookies ранее разделённых токенов. Используйте для Node, MCP и приложений, которым нужны полные токены для API-вызовов, выпуска интеграционного ключа и cleanup. |
+| `true` | При наличии access token разделяет access/refresh: одну часть каждого токена помещает в HttpOnly cookies, другую возвращает в JSON. Используйте только для браузерного приложения, специально настроенного на этот режим авторизации. При Mobile ID без готовых токенов разделение пропускается. |
+| Не задано | Flow не отправляет поле. В текущей реализации шлюза отсутствующий boolean имеет значение `false`; для явно выбранного режима полных токенов задавайте `false`. |
+
+В режиме `true` поля `result.tokens` содержат части токенов, а не самостоятельные полные Bearer/refresh-токены. Последующие запросы должны передавать необходимые части и cookies для восстановления токенов шлюзом. Приложение обеспечивает работу с cookies, включая `credentials` у `fetch` и разрешения CORS при запросах между origin. SDK не добавляет cookie jar или управление cookies; стандартный Node `fetch` не сохраняет и не передаёт их автоматически между запросами. Поэтому Node-примеры задают `splitTokens: false`. Тесты SDK проверяют передачу обоих значений в HTTP-тело, а не серверное разделение или браузерную работу cookies.
+
+Challenge: `sessionId`, `accountType`, `usedMethod`, `phase`, `expiresAtMs` и проверенные подсказки `codeLength`, `pollIntervalSeconds`, `attemptsRemaining`, `nextSendAtMs`, `availableMethods`. Даты — Unix milliseconds, пригодные для JSON. Токенов/OTP в challenge нет. Проверка структуры SDK не заменяет проверку целостности приложением. Между шагами приложение сохраняет тот же deviceInfo, scopes и splitTokens; flow не связывает их криптографически с challenge.
+
+Срок отсчитывается от начала start: серверный sessionLifeTimeInSeconds либо локальные 180 секунд при отсутствии/null. Некорректный TTL отклоняется. Локальный срок не гарантирует действие сессии на сервере и не продлевается. Ограничение 600 секунд относится к MCP. Polling hint default — 3 секунды. Некорректные необязательные подсказки пропускаются; длина кода — корректная серверная либо Email 6, Phone/SMS fallback 4. Число попыток не уменьшается самостоятельно.
+
+Перед проверкой token-ответа нормализуются существующие aliases: AccessToken/access_token, RefreshToken/refresh_token, Expiration/expires_in, Status. Приоритет: имя OpenAPI → PascalCase → snake_case по первому значению, отличному от null/undefined. Flow требует явный известный status и непустой access token при TokenReady. Старые методы сохраняют ответы без status, только с refresh token и прежние callback-поля через внутреннюю legacy-адаптацию общей реализации.
+
+`OtpFlowError.code`: InvalidArguments, InvalidChallenge, InvalidResponse, UnsupportedMethod. Getter `error.cleanup` передаёт обнаруженный refresh даже при повреждённом ответе; он не включён в обычную сериализацию/диагностику ошибки. Валидные незавершённые/Failed ответы передают refresh через result.cleanup. HTTP-ошибки остаются TorrowHttpError, сеть и отмена пробрасываются. Потеря ответа не разрешает слепой повтор. Signal передаётся до fetch на обоих шагах; некорректный/просроченный challenge отклоняется до upstream.
+
+Примеры: auth-otp-flow.ts (JSON и новый flow), auth-otp-flow-mobile-id.ts (polling приложения и SMS fallback). Выпуск интеграционного ключа, подтверждение identity и cleanup выполняются приложением.
+
+Общая база `{ tokenStorage, deviceInfo }` (+ опционально `appCredentials`) у режимов с сессией.
+Без `appCredentials` — **`DEFAULT_APP_CREDENTIALS`** (`sdk.torrow.net`). Своя пара перекрывает дефолт.
+
+### 1. Restore + OTP при необходимости
+
+```ts
+import { TorrowAuth } from "@torrow/sdk-auth";
+import { FileTokenStorage } from "@torrow/sdk-auth/node";
+import { DeviceTypeValues } from "@torrow/sdk-client";
+
+const base = {
+  // appCredentials опционален — иначе DEFAULT_APP_CREDENTIALS
+  tokenStorage: new FileTokenStorage("./.torrow-session.json"),
+  deviceInfo: { deviceId: "pos-terminal-1", deviceType: DeviceTypeValues.Desktop },
+  userAgent: "my-app/1.0",
+};
+
+let { client, session } = await TorrowAuth.connect(base);
+
+if (session.status !== "authenticated") {
+  ({ client, session } = await TorrowAuth.loginWithOtp({
+    ...base,
+    account: { accountType: "Phone", accountName: "+79001234567" },
+    onSendCode: (d) => showHint(d.usedMethod, d.codeLength),
+    getCode: (ctx) => promptUser(ctx.codeLength),
+  }));
+}
+
+await client.profiles.list();
+```
+
+Чтобы задать свои креды приложения:
+
+```ts
+appCredentials: { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET },
+```
+
+### 2. Mobile ID / смена канала / rate-limit
+
+```ts
+import { OtpCodeRequestLimitExceededError } from "@torrow/sdk-auth";
+
+try {
+  await TorrowAuth.loginWithOtp({
+    ...base,
+    account: { accountType: "Phone", accountName: phone },
+    supportedMethods: ["MtsMobileId", "Sms"],
+    preferredMethod: userPickedMethod,
+    onSendCode: (d) => {
+      // MtsMobileId → UI «подтвердите push»; getCode не вызовется на happy-path
+      renderLoginUi(d);
+    },
+    getCode: (ctx) => waitCodeInput(ctx),
+  });
+} catch (e) {
+  if (e instanceof OtpCodeRequestLimitExceededError) {
+    showRetryTimer(e.minutes, e.seconds);
+  } else {
+    throw e;
+  }
+}
+```
+
+### 3. Telegram deep-link
+
+```ts
+const { client, session } = await TorrowAuth.loginWithLink({
+  ...base,
+  onLink: (authUrl) => showQrOrOpen(authUrl),
+  signal: abortController.signal,
+});
+```
+
+### 4. Виджет: токены от хоста
+
+```ts
+import { TorrowAuth, LocalStorageTokenStorage } from "@torrow/sdk-auth";
+
+const { client, session } = await TorrowAuth.fromTokens({
+  accessToken: hostProvidedAccess,
+  refreshToken: hostProvidedRefresh,
+  appCredentials: hostProvidedAppCreds,
+  tokenStorage: new LocalStorageTokenStorage("torrow.widget.session"),
+  deviceInfo: { deviceId: widgetDeviceId(), deviceType: DeviceTypeValues.Web },
+});
+
+session.onStatusChange((s) => {
+  if (s !== "authenticated") widgetUi.showLoginPrompt();
+});
+```
+
+### 5. Аноним и выход
+
+```ts
+const publicClient = TorrowAuth.anonymous({ userAgent: "my-widget" });
+
+await session.logout(); // revoke refresh + clear storage + onStatusChange("unauthenticated")
+```
+
+## Сигналы UI
+
+| Сигнал от SDK | Что делает App |
+|---------------|----------------|
+| **`onSendCode({ usedMethod: Sms, codeLength, … })`** | Форма/подсказка «код в SMS»; длина поля = `codeLength` |
+| **`onSendCode({ usedMethod: TelegramGateway, codeLength })`** | Форма «код в Telegram» (**не** deep-link) |
+| **`onSendCode({ usedMethod: FlashCall, codeLength })`** | Подсказка «цифры из звонка» |
+| **`onSendCode({ accountType: Email, codeLength })`** | Форма «код на email» |
+| **`onSendCode({ usedMethod: MtsMobileId })`** | Ожидание push **без** keypad (`codeLength` часто `0`) |
+| **`getCode({ codeLength })`** | Дождаться ввода; валидировать по `codeLength` (экран уже из `onSendCode`) |
+| **`onLink(authUrl)`** (`loginWithLink`) | Показать QR / открыть Telegram; **код OTP не вводить** |
+| **`session.onStatusChange`** | Реактивный login-state (`authenticated` / `unauthenticated` / `expired`) |
+
+## Sequence: OTP (`loginWithOtp`)
+
+```mermaid
+sequenceDiagram
+  participant User as User
+  participant App
+  participant SdkAuth as sdk_auth
+  participant Auth as client.auth
+
+  User->>App: телефон или email
+  App->>SdkAuth: TorrowAuth.loginWithOtp
+  SdkAuth->>Auth: sendCode
+  Auth-->>SdkAuth: usedMethod sessionId codeLength
+  SdkAuth->>App: onSendCode account usedMethod codeLength
+
+  alt usedMethod MtsMobileId
+    Note over App,User: onSendCode MtsMobileId без keypad
+    App->>User: UI ожидание push
+    loop пока Pending
+      SdkAuth->>Auth: requestToken code empty
+      Auth-->>SdkAuth: status Pending
+    end
+    opt status AwaitingSmsCode
+      Note over SdkAuth,App: показать SMS-форму
+      SdkAuth->>App: getCode codeLength
+      App->>User: форма SMS-кода
+      User->>App: ввод SMS-кода
+      App-->>SdkAuth: code
+      SdkAuth->>Auth: requestToken with code
+    end
+  else classic Sms FlashCall TelegramGateway Email
+    Note over App,User: onSendCode usedMethod в т.ч. TelegramGateway
+    App->>User: форма или подсказка под usedMethod
+    SdkAuth->>App: getCode codeLength
+    User->>App: ввод кода
+    App-->>SdkAuth: code
+    SdkAuth->>Auth: requestToken with code
+  end
+
+  Auth-->>SdkAuth: TokenReady
+  SdkAuth->>SdkAuth: persist TokenStorage
+  SdkAuth-->>App: client plus session
+  App->>User: вход выполнен
+```
+
+## Sequence: Telegram (`loginWithLink`)
+
+```mermaid
+sequenceDiagram
+  participant User as User
+  participant App
+  participant SdkAuth as sdk_auth
+  participant Auth as client.auth
+  participant Bot as TelegramBot
+
+  User->>App: войти через Telegram
+  App->>SdkAuth: TorrowAuth.loginWithLink
+  SdkAuth->>Auth: createSession
+  Auth-->>SdkAuth: sessionId code authUrl
+  SdkAuth->>App: onLink authUrl
+  App->>User: QR или открыть authUrl
+  User->>Bot: Start
+  Bot->>Auth: VerifyAuthSession
+  loop пока не ready
+    SdkAuth->>Auth: requestToken sessionId code
+    Auth-->>SdkAuth: not ready или TokenReady
+  end
+  SdkAuth->>SdkAuth: persist TokenStorage
+  SdkAuth-->>App: client plus session
+  App->>User: вход выполнен
+```
+
+## Sequence: connect / refresh / 401 / logout
+
+```mermaid
+sequenceDiagram
+  participant User as User
+  participant App
+  participant SdkAuth as sdk_auth
+  participant Api as TorrowAPI
+  participant Auth as client.auth
+
+  App->>SdkAuth: TorrowAuth.connect
+  SdkAuth->>SdkAuth: TokenStorage.load
+  alt access свежий
+    SdkAuth-->>App: client plus session authenticated
+  else есть refreshToken
+    SdkAuth->>Auth: refresh
+    Auth-->>SdkAuth: TokenReady
+    SdkAuth->>SdkAuth: persist
+    SdkAuth-->>App: client plus session authenticated
+  else нет токенов
+    SdkAuth-->>App: session unauthenticated
+    Note over App: далее loginWithOtp или loginWithLink
+  end
+
+  User->>App: действие API
+  App->>Api: Bearer request
+  alt 401 и refreshOnUnauthorized
+    Api-->>SdkAuth: 401
+    SdkAuth->>Auth: refresh
+    Auth-->>SdkAuth: TokenReady
+    SdkAuth->>Api: retry once
+    Api-->>App: 200
+  else access истекает по skew
+    SdkAuth->>Auth: proactive refresh
+    Auth-->>SdkAuth: TokenReady
+  end
+
+  opt logout
+    App->>SdkAuth: session.logout
+    SdkAuth->>Auth: revoke
+    SdkAuth->>SdkAuth: clear TokenStorage
+    SdkAuth->>App: onStatusChange unauthenticated
+  end
+```
+
+## Sequence: fromTokens + onStatusChange
+
+```mermaid
+sequenceDiagram
+  participant Host as HostApp
+  participant App as Widget
+  participant SdkAuth as sdk_auth
+
+  Host->>App: accessToken refreshToken optional
+  App->>SdkAuth: TorrowAuth.fromTokens
+  SdkAuth->>SdkAuth: save to TokenStorage
+  SdkAuth-->>App: client plus session
+  SdkAuth->>App: onStatusChange authenticated
+  Note over App,SdkAuth: дальше как connect refresh 401
+  opt access истёк без refresh или logout
+    SdkAuth->>App: onStatusChange expired or unauthenticated
+    App->>Host: запросить новый логин
+  end
+```
+
+## Storage
+
+| Класс | Назначение |
+|-------|------------|
+| **`MemoryTokenStorage`** | Тесты, эфемерные процессы, без диска |
+| **`FileTokenStorage`** | Node-only (`node:fs`): JSON-файл — **`@torrow/sdk-auth/node`** (канон для `examples/node/**`) |
+| **`LocalStorageTokenStorage`** | Браузер / виджет: `localStorage` |
+| custom **`TokenStorage`** | IndexedDB, SecureStore, … — `load` / `save` снаружи |
+
+**Node vs browser:** главный вход `@torrow/sdk-auth` browser-safe. `FileTokenStorage` — только `import { FileTokenStorage } from "@torrow/sdk-auth/node"` (тянет `node:fs`).
+
+**JWT vs integration key:** user JWT обычно с `exp` в payload; opaque/integration key — строка без JWT-формы.
+
+- **Opaque (non-JWT-shaped):** меньше 3 сегментов через точку (не `a.b.c`); host TTL через `TorrowAuth.fromTokens({ accessExpiresAtMs })` или бессрочно без TTL
+- **JWT-shaped undecodable (`a.b.c`):** `isAccessStillFresh` всегда false → proactive refresh на `open` / `ensureFresh`, пока есть `refreshToken`; после refresh **без** `expiration` merge сбрасывает snapshot TTL → opaque unlimited → дальнейший proactive refresh не идёт (не refresh-storm)
+- **Valid JWT:** runtime freshness AND-ит `exp`; будущий explicit `accessExpiresAtMs` не оживит просроченный JWT
+- **Opaque host TTL в skew-окне** (`accessTokenSkewMs`, default 30s): refresh без `expiration` сбрасывает snapshot TTL → бессрочный opaque до 401 (лучше refresh-storm)
+
+Host: non-JWT-shaped opaque **или** валидный JWT с `exp`.
+
+Канон examples: `new FileTokenStorage(path)` + `TorrowAuth.connect` / `loginWithOtp` — без ручного dual deviceInfo provider.
+
+## API (кратко)
+
+| API | Роль |
+|-----|------|
+| **`TorrowAuth.connect`** | restore / refresh → `{ client, session }`; **без** OTP |
+| **`TorrowAuth.loginWithOtp`** | sendCode → Mobile ID / classic → persist |
+| **`TorrowAuth.loginWithLink`** | Telegram deep-link → poll → persist |
+| **`TorrowAuth.fromTokens`** | сид access[/refresh] → connect-семантика |
+| **`TorrowAuth.anonymous`** | `TorrowClient` без Bearer |
+| **`TokenSession`** | `status`, `onStatusChange`, `logout`, `requestTokenWithCode`, `refresh`, `client` |
+| **`refreshOnUnauthorized`** | 401 → refresh → один retry (**default true**) |
+| **`onRefreshFailure`** | optional; политика при ошибке refresh (`keep` / `clear` / `throw`); default: non-HTTP / network → `keep`; HTTP 429/502–504 → `keep`; other HTTP → `clear` |
+
+`appCredentials: { clientId, clientSecret }` (опционально; иначе **`DEFAULT_APP_CREDENTIALS`**)
+внутри auth-пакета мапится на **`AuthIdentityBasic`**
+(`username`/`password`) → **`TorrowClientConfig.authIdentityBasic`**. Маппер **не** публичный API:
+приложениям достаточно **`appCredentials`** или дефолта; low-level `TorrowClient` собирает Basic сам
+(см. **`examples/node/auth/auth-send-code.ts`**).
+
+**401-retry** вызывает только **refresh**, не OTP.