@torrow/sdk-auth 0.6.0 → 0.8.0

package/README.md

@@ -13,6 +13,7 @@ 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"]
@@ -27,6 +28,139 @@ flowchart TD
 
 ## Целевой клиентский код
 
+### Приоритет способов подтверждения для телефона
+
+Порядок `supportedMethods` имеет значение: передавайте поддерживаемые клиентом способы в порядке приоритета. Для телефона рекомендуется следующий порядок (для `loginWithOtp`, `createOtpFlow().start` и low-level `sendCode`):
+
+```ts
+import { VerificationMethodValues } from "@torrow/sdk-client";
+
+supportedMethods: [
+  VerificationMethodValues.TelegramGateway,
+  VerificationMethodValues.MtsMobileId,
+  VerificationMethodValues.Sms,
+],
+```
+
+`preferredMethod` задаёт отдельное пожелание, а фактический способ сервер возвращает в `usedMethod`. Указывайте только способы, которые приложение умеет обрабатывать. Примеры, специально посвящённые Mobile ID, задают свой список; пример classic OTP без polling исключает `MtsMobileId` и сохраняет порядок `TelegramGateway`, `Sms`.
+
+### Пошаговый 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`). Своя пара перекрывает дефолт.
 
@@ -35,7 +169,7 @@ flowchart TD
 ```ts
 import { TorrowAuth } from "@torrow/sdk-auth";
 import { FileTokenStorage } from "@torrow/sdk-auth/node";
-import { DeviceTypeValues } from "@torrow/sdk-client";
+import { DeviceTypeValues, VerificationMethodValues } from "@torrow/sdk-client";
 
 const base = {
   // appCredentials опционален — иначе DEFAULT_APP_CREDENTIALS
@@ -50,6 +184,11 @@ if (session.status !== "authenticated") {
   ({ client, session } = await TorrowAuth.loginWithOtp({
     ...base,
     account: { accountType: "Phone", accountName: "+79001234567" },
+    supportedMethods: [
+      VerificationMethodValues.TelegramGateway,
+      VerificationMethodValues.MtsMobileId,
+      VerificationMethodValues.Sms,
+    ],
     onSendCode: (d) => showHint(d.usedMethod, d.codeLength),
     getCode: (ctx) => promptUser(ctx.codeLength),
   }));
@@ -68,12 +207,17 @@ appCredentials: { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET },
 
 ```ts
 import { OtpCodeRequestLimitExceededError } from "@torrow/sdk-auth";
+import { VerificationMethodValues } from "@torrow/sdk-client";
 
 try {
   await TorrowAuth.loginWithOtp({
     ...base,
     account: { accountType: "Phone", accountName: phone },
-    supportedMethods: ["MtsMobileId", "Sms"],
+    supportedMethods: [
+      VerificationMethodValues.TelegramGateway,
+      VerificationMethodValues.MtsMobileId,
+      VerificationMethodValues.Sms,
+    ],
     preferredMethod: userPickedMethod,
     onSendCode: (d) => {
       // MtsMobileId → UI «подтвердите push»; getCode не вызовется на happy-path