@torrow/sdk-auth 0.7.0 → 0.9.0

package/README.md

@@ -28,6 +28,22 @@ 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`.
@@ -76,8 +92,8 @@ sequenceDiagram
 ```
 
 ```ts
-import { TorrowAuth, OtpFlowError, type OtpChallenge } from "@torrow/sdk-auth";
-import { TokenStatusValues } from "@torrow/sdk-client";
+import { TorrowAuth, type OtpChallenge } from "@torrow/sdk-auth";
+import { TokenStatusValues, TorrowSdkError } from "@torrow/sdk-client";
 
 const options = {
   deviceInfo: { deviceId: "my-app-device", deviceType: "Desktop" as const },
@@ -104,8 +120,9 @@ try {
     }
   }
 } catch (error) {
-  if (error instanceof OtpFlowError) {
-    // error.code — безопасная причина; error.cleanup?.refreshToken — секрет для cleanup.
+  if (error instanceof TorrowSdkError) {
+    // error.detail — безопасная предметная причина;
+    // error.getSensitiveDetails().cleanup?.refreshToken — секрет для cleanup.
     // Cleanup выполняет приложение с независимым AbortSignal.
   }
   throw error;
@@ -141,7 +158,7 @@ Challenge: `sessionId`, `accountType`, `usedMethod`, `phase`, `expiresAtMs` и
 
 Перед проверкой 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.
+`TorrowSdkError.category` достаточна для общей обработки. `detail` сохраняет домен `TorrowSdkErrorDomain.Otp` и необязательную дополнительную причину `OtpErrorReason.InvalidChallenge`, `UnsupportedMethod`, `AuthHeaderMissing` или `CodeRequestLimitExceeded`; generic InvalidInput/InvalidResponse не дублируются причинами. Метод `error.getSensitiveDetails().cleanup` передаёт обнаруженный refresh даже при повреждённом ответе; он не включён в обычную сериализацию/диагностику ошибки. Валидные незавершённые/Failed ответы передают refresh через result.cleanup. HTTP, сеть, отмена и предметные отказы используют общий TorrowSdkError. OTP start/complete не создают effects; status=Failed остаётся результатом. Потеря ответа не разрешает слепой повтор. Signal передаётся до fetch на обоих шагах; некорректный/просроченный challenge отклоняется до upstream.
 
 Примеры: auth-otp-flow.ts (JSON и новый flow), auth-otp-flow-mobile-id.ts (polling приложения и SMS fallback). Выпуск интеграционного ключа, подтверждение identity и cleanup выполняются приложением.
 
@@ -153,7 +170,7 @@ Challenge: `sessionId`, `accountType`, `usedMethod`, `phase`, `expiresAtMs` и
 ```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
@@ -168,6 +185,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),
   }));
@@ -185,13 +207,18 @@ appCredentials: { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET },
 ### 2. Mobile ID / смена канала / rate-limit
 
 ```ts
-import { OtpCodeRequestLimitExceededError } from "@torrow/sdk-auth";
+import { TorrowAuth } from "@torrow/sdk-auth";
+import { TorrowSdkError, TorrowSdkErrorDomain, OtpErrorReason, 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
@@ -200,8 +227,8 @@ try {
     getCode: (ctx) => waitCodeInput(ctx),
   });
 } catch (e) {
-  if (e instanceof OtpCodeRequestLimitExceededError) {
-    showRetryTimer(e.minutes, e.seconds);
+  if (e instanceof TorrowSdkError && e.detail?.domain === TorrowSdkErrorDomain.Otp && e.detail.reason === OtpErrorReason.CodeRequestLimitExceeded) {
+    showRetryTimer(e.detail.retryAfterSeconds);
   } else {
     throw e;
   }
@@ -436,3 +463,20 @@ Host: non-JWT-shaped opaque **или** валидный JWT с `exp`.
 (см. **`examples/node/auth/auth-send-code.ts`**).
 
 **401-retry** вызывает только **refresh**, не OTP.
+
+
+## Ошибки пользовательской сессии
+
+`TokenSession.open/getAccessToken/ensureFresh/requestTokenWithCode/refresh/applyTokenResp/clearTokens/logout` и `TorrowAuth.connect/fromTokens` сообщают отказ через `TorrowSdkError` из `@torrow/sdk-client`. `category` описывает причину, `detail` содержит домен `AuthSession` и optional reason только для `SessionNotReady` / `CallbackFailed`; generic и storage-причины удалены, этапы storage различает `failureAt`, `operation` и `failureAt` называют метод и локальную стадию без аргументов. `AuthSessionNotReadyError` удалён: ожидающую подтверждения сессию распознавайте через `detail.domain === TorrowSdkErrorDomain.AuthSession` и `detail.reason === AuthSessionErrorReason.SessionNotReady`. Штатный polling deep-link сохранён.
+
+`effects` описывает только предметные изменения текущего вызова: Remote (`IssueTokens`, `RefreshTokens`, `RevokeTokens`), SessionMemory (`SetTokens`, `ClearTokens`, `CloseSession`), Storage (`SaveTokens`, `ClearStorage`). `Applied` подтверждает шаг, `Unknown` не разрешает слепой повтор. После успешного refresh и ошибки `storage.save` серверный refresh и новая память имеют `Applied`, сохранение — `Unknown`, причина — `StorageFailure`. Память не откатывается. У `fromTokens` подтверждение сохранённого seed сохраняется при ошибке последующего connect. При logout ошибка revoke подавляется; если позже падает storage, неизвестный результат revoke остаётся в effects, сессия остаётся закрытой и память очищенной.
+
+`onRefreshFailure` получает `TorrowSdkError`. По умолчанию HTTP 429/502/503/504 и все не-HTTP причины (включая storage) выбирают `keep`; остальные HTTP отказы — `clear`. `keep` не выполняет дополнительную очистку, но не отменяет уже изменённую память. `ensureFresh/getAccessToken/connect` с политикой keep/clear сохраняют прежнее завершение без throw; явный refresh сообщает отказ. Callback `throw` делает ошибку наблюдаемой и при проактивном refresh. Storage-сбой при очистке сообщает собственную причину с выполненными шагами, а не ошибку сервера.
+
+Обычный запрос клиента с 401-refresh не обещает полный аудит авторизации. Отсутствие effects означает отсутствие сведений, а не отсутствие изменений. Последняя сохранённая refresh-причина и параллельные вызовы не переносят историю независимых операций. Прямые `TokenStorage.load/save` сохраняют собственные исключения; штатные fallback хранилищ не меняются. Исходная причина/ответ доступны через `getSensitiveDetails()` и могут содержать секреты; обычные message/JSON/console безопасны.
+
+### Диагностика составного логина
+
+`loginWithOtp` и `loginWithLink` сообщают `operation`, локальную `failureAt` и неизменяемые `effects` выбранных шагов текущего вызова: инициализация сессии, отправка кода (`SendCode`) либо создание продолжения ссылки (`CreateAuthSession`), выдача токенов, память и сохранение. Подтверждённый шаг сохраняет `Applied`, даже если следующий callback или storage завершается ошибкой. Возможные внутренние действия callback не перечисляются.
+
+При ошибке сохранения после token-ответа серверная выдача и память могут быть `Applied`, а storage — `Unknown`. Отсутствие effects у обычной сетевой ошибки или пошагового flow не доказывает отсутствие изменений. Диагностика не разрешает слепой повтор; приложение принимает решение о восстановлении. Исходные body/URL/cause и cleanup доступны явно через `getSensitiveDetails()` и не предназначены для обычного логирования.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { A as AppCredentials, T as TokenSessionOptions, a as TokenStorage, b as TokenSessionStatus, c as TokenSessionStatusListener, d as AuthTokenSnapshot } from './types-C4e90uOw.js';
-export { R as RefreshFailureAction } from './types-C4e90uOw.js';
-import { SendCodeAccountType, VerificationMethod, TorrowClient, DeviceInfo, TokenResp, AuthScope, AuthCaptchaType, AccountType, TokenStatusValues } from '@torrow/sdk-client';
+import { A as AppCredentials, T as TokenSessionOptions, a as TokenStorage, b as TokenSessionStatus, c as TokenSessionStatusListener, d as AuthTokenSnapshot } from './types-M7DBG6bO.js';
+export { R as RefreshFailureAction } from './types-M7DBG6bO.js';
+import { SendCodeAccountType, VerificationMethod, TorrowSdkEffect, TorrowClient, DeviceInfo, TokenResp, AuthScope, AuthCaptchaType, AccountType, TokenStatusValues } from '@torrow/sdk-client';
 
 /** Defaults и преобразование credentials приложения в HTTP Basic. */
 
@@ -72,23 +72,6 @@ type OtpGetCodeContext = {
     /** Канал из `sendCode` (опциональная подсказка; экран уже из `onSendCode`). */
     usedMethod?: VerificationMethod;
 };
-/** Превышен лимит `sendCode` (`CODE_REQUEST_LIMIT_EXCEEDED`). */
-declare class OtpCodeRequestLimitExceededError extends Error {
-    readonly name = "OtpCodeRequestLimitExceededError";
-    readonly minutes?: string;
-    readonly seconds?: string;
-    readonly traceUrl?: string;
-    readonly apiMessage?: string;
-    readonly body: unknown;
-    constructor(body: unknown);
-}
-/** Нет Basic на `/auth/token` (`AUTH_HEADER_MISSING`). */
-declare class OtpAuthHeaderMissingError extends Error {
-    readonly name = "OtpAuthHeaderMissingError";
-    readonly body: unknown;
-    readonly systemMessage?: string;
-    constructor(body: unknown);
-}
 
 /**
  * Ядро пользовательской сессии: persist + проактивный refresh + single-flight + 401-retry.
@@ -114,7 +97,18 @@ declare class TokenSession {
     /** Set in refreshWithFailurePolicy catch; not cleared on success (see public refresh). */
     private lastRefreshError;
     private constructor();
+    /** Открыть сессию; storage/refresh ошибки описывают только выполненную инициализацию. */
     static open(opts: TokenSessionOptions): Promise<TokenSession>;
+    /**
+     * @internal Инициализация с явными сведениями только текущего вызова для составного login.
+     * Не наблюдает fetch/storage и не хранит историю независимых операций.
+     */
+    static openWithEffects(opts: TokenSessionOptions): Promise<{
+        /** Открытая сессия с прежней семантикой open. */
+        session: TokenSession;
+        /** Неизменяемый снимок реально выполненных шагов инициализации. */
+        effects: readonly TorrowSdkEffect[];
+    }>;
     /** Persist, переданный в `TokenSession.open` / `TorrowAuth.*`. */
     get tokenStorage(): TokenStorage;
     get client(): TorrowClient;
@@ -126,6 +120,7 @@ declare class TokenSession {
     getTokenSnapshot(): AuthTokenSnapshot;
     /** `deviceInfo` из options open или fallback Desktop + deviceId из tokenSnapshot. */
     getDeviceInfo(): DeviceInfo;
+    /** Получить access после проактивного refresh; closed возвращает undefined без записи. */
     getAccessToken(): Promise<string | undefined>;
     /**
      * Сохранить ответ `requestToken` / `refresh` (только TokenReady).
@@ -135,6 +130,7 @@ declare class TokenSession {
     applyTokenResp(tokens: TokenResp, opts?: {
         replace?: boolean;
     }): Promise<void>;
+    /** Очистить память и сохранить snapshot; storage-сбой не отменяет очистку памяти. */
     clearTokens(): Promise<void>;
     /**
      * Revoke refresh (если есть) + очистка storage.
@@ -147,15 +143,19 @@ declare class TokenSession {
      *
      * Один вызов `POST /api/v1/auth/token` (`requestToken`) с `{ sessionId, code }`.
      * При успехе (`TokenReady`) — persist; если сессия ещё не готова —
-     * {@link AuthSessionNotReadyError} (поллинг для deep-link — внутри `TorrowAuth.loginWithLink`).
+     * `TorrowSdkError` с причиной `SessionNotReady` (поллинг для deep-link — внутри `TorrowAuth.loginWithLink`).
      *
      * HTTP вне mutex; persist сериализован через {@link applyTokenResp} (не оборачивать
      * весь метод в `runExclusive` — вложенный mutex с публичным `applyTokenResp`).
      */
     requestTokenWithCode(args: {
+        /** Идентификатор ранее созданной серверной auth-сессии. */
         sessionId: string;
+        /** Одноразовый код доступа для выдачи токенов. */
         code: string;
+        /** Права токенов; при отсутствии используются DefaultAuthScopes. */
         scopes?: AuthScope[];
+        /** Отмена единственного серверного запроса выдачи. */
         signal?: AbortSignal;
     }): Promise<TokenResp>;
     /**
@@ -165,6 +165,7 @@ declare class TokenSession {
      * не используй return value; смотри `session.status` / `getTokenSnapshot()`.
      */
     refresh(): Promise<TokenResp>;
+    /** Обновить просроченный access; политика keep/clear сохраняет прежнее resolve-поведение. */
     ensureFresh(): Promise<void>;
     private assertNotClosedForWrite;
     /** Caller must hold `runExclusive`. Do not call public `applyTokenResp` from here. */
@@ -172,7 +173,7 @@ declare class TokenSession {
     private clearTokensUnlocked;
     /** Caller must hold `runExclusive`. `refreshWithFailurePolicy` skips when no refreshToken; guard here is intentional defense-in-depth. */
     private refreshUnlocked;
-    /** Caller must hold `runExclusive`. */
+    /** Caller must hold `runExclusive`; сведения принадлежат только текущей операции. */
     private refreshWithFailurePolicy;
     private runExclusive;
     private ensureFreshImpl;
@@ -258,6 +259,7 @@ type TorrowAuthLoginWithOtpOptions = TorrowAuthSessionBase & {
     preferredMethod?: VerificationMethod;
     /**
      * Capability клиента → `SendCodeReq.supportedMethods`.
+     * Порядок задаёт приоритет: для телефона рекомендуется `TelegramGateway`, `MtsMobileId`, `Sms`.
      * Без `MtsMobileId` сервер обычно не выберет Mobile ID.
      */
     supportedMethods?: VerificationMethod[];
@@ -307,9 +309,11 @@ type TorrowAuthFromTokensOptions = TorrowAuthSessionBase & {
 declare const TorrowAuth: {
     /** Пошаговый OTP без storage, polling и refresh. */
     readonly createOtpFlow: typeof createOtpFlow;
+    /** Загрузить сессию; общий отказ сохраняет текущую диагностику open/refresh. */
     readonly connect: (options: TorrowAuthConnectOptions) => Promise<TorrowAuthResult>;
     readonly loginWithOtp: (options: TorrowAuthLoginWithOtpOptions) => Promise<TorrowAuthResult>;
     readonly loginWithLink: (options: TorrowAuthLoginWithLinkOptions) => Promise<TorrowAuthResult>;
+    /** Сохранить host tokens, затем connect; последующий отказ не отменяет Applied сохранение. */
     readonly fromTokens: (options: TorrowAuthFromTokensOptions) => Promise<TorrowAuthResult>;
     readonly anonymous: (config?: Pick<TokenSessionOptions, "baseUrl" | "fetch" | "defaultHeaders" | "userAgent">) => TorrowClient;
 };
@@ -358,7 +362,8 @@ type TorrowAuthOtpFlowOptions = Pick<TokenSessionOptions, "baseUrl" | "fetch" |
  * account задаёт Phone/Email и получателя; language — язык (default ru),
  * regionStorageId — регион (default 70), captcha/captchaType — ответ и провайдер captcha,
  * inviteSessionId — приглашение. preferredMethod — пожелание серверу,
- * supportedMethods — способы, которые приложение умеет обработать.
+ * supportedMethods — способы, которые приложение умеет обработать, в порядке приоритета.
+ * Для телефона рекомендуется TelegramGateway → MtsMobileId → Sms.
  * UI и получение captcha остаются в приложении.
  */
 type OtpStartInput = Pick<TorrowAuthLoginWithOtpOptions, "account" | "language" | "regionStorageId" | "captcha" | "captchaType" | "inviteSessionId" | "preferredMethod" | "supportedMethods">;
@@ -416,31 +421,6 @@ type OtpCleanupData = {
     /** Refresh-секрет для явного отзыва приложением; не предназначен для диагностики. */
     refreshToken: string;
 };
-/** Причины локального отказа; HTTP и отмена пробрасываются без преобразования. */
-declare enum OtpFlowErrorCodeValues {
-    /** Некорректные опции, вход start или код для текущей фазы. */
-    InvalidArguments = "InvalidArguments",
-    /** Повреждённое, противоречивое или просроченное продолжение. */
-    InvalidChallenge = "InvalidChallenge",
-    /** Ответ не соответствует строгому контракту шага. */
-    InvalidResponse = "InvalidResponse",
-    /** Фактический способ подтверждения отсутствует или не поддерживается для аккаунта. */
-    UnsupportedMethod = "UnsupportedMethod"
-}
-/** Строковое представление безопасной причины отказа. */
-type OtpFlowErrorCode = `${OtpFlowErrorCodeValues}`;
-/** Отказ с безопасной диагностикой и отдельно доступным секретом для cleanup. */
-declare class OtpFlowError extends Error {
-    #private;
-    /** Безопасная причина локального отказа, без исходного ответа и секретов. */
-    readonly code: OtpFlowErrorCode;
-    readonly name = "OtpFlowError";
-    constructor(
-    /** Безопасная причина локального отказа, без исходного ответа и секретов. */
-    code: OtpFlowErrorCode, cleanup?: OtpCleanupData);
-    /** Секрет доступен явно; не является перечисляемым полем исключения. */
-    get cleanup(): OtpCleanupData | undefined;
-}
 /**
  * Результат одного шага: серверный статус отдельно от фазы challenge.
  * Pending — сервер ещё не завершил аутентификацию, следующий запрос без кода.
@@ -490,7 +470,7 @@ interface OtpFlow {
  * Challenge и токены остаются у приложения, без storage, polling и refresh внутри flow.
  * @param options Настройки HTTP, credentials приложения, устройства и выдачи токенов.
  * @returns Независимые шаги отправки кода и завершения/ожидания аутентификации.
- * @throws OtpFlowError При некорректных опциях устройства, scopes или splitTokens.
+ * @throws TorrowSdkError При некорректных опциях устройства, scopes или splitTokens.
  */
 declare function createOtpFlow(options: TorrowAuthOtpFlowOptions): OtpFlow;
 
@@ -533,11 +513,4 @@ declare class LocalStorageTokenStorage implements TokenStorage {
     save(snapshot: AuthTokenSnapshot): Promise<void>;
 }
 
-/** Сессия auth ещё не подтверждена (например Telegram до Start у бота). */
-declare class AuthSessionNotReadyError extends Error {
-    readonly name = "AuthSessionNotReadyError";
-    readonly cause?: unknown;
-    constructor(message?: string, cause?: unknown);
-}
-
-export { AppCredentials, AuthSessionNotReadyError, AuthTokenSnapshot, DEFAULT_APP_CREDENTIALS, LocalStorageTokenStorage, MemoryTokenStorage, OtpAuthHeaderMissingError, type OtpChallenge, type OtpCleanupData, OtpCodeRequestLimitExceededError, type OtpCompleteInput, type OtpCompleteResult, type OtpFlow, OtpFlowError, type OtpFlowErrorCode, OtpFlowErrorCodeValues, type OtpGetCodeContext, type OtpPhase, OtpPhaseValues, type OtpRequestOptions, type OtpSendCodeResult, type OtpStartInput, TokenSession, TokenSessionOptions, TokenSessionStatus, TokenSessionStatusListener, TokenStorage, TorrowAuth, type TorrowAuthAccount, type TorrowAuthConnectOptions, type TorrowAuthFromTokensOptions, type TorrowAuthLoginWithLinkOptions, type TorrowAuthLoginWithOtpOptions, type TorrowAuthOtpFlowOptions, type TorrowAuthResult, type TorrowAuthSessionBase };
+export { AppCredentials, AuthTokenSnapshot, DEFAULT_APP_CREDENTIALS, LocalStorageTokenStorage, MemoryTokenStorage, type OtpChallenge, type OtpCleanupData, type OtpCompleteInput, type OtpCompleteResult, type OtpFlow, type OtpGetCodeContext, type OtpPhase, OtpPhaseValues, type OtpRequestOptions, type OtpSendCodeResult, type OtpStartInput, TokenSession, TokenSessionOptions, TokenSessionStatus, TokenSessionStatusListener, TokenStorage, TorrowAuth, type TorrowAuthAccount, type TorrowAuthConnectOptions, type TorrowAuthFromTokensOptions, type TorrowAuthLoginWithLinkOptions, type TorrowAuthLoginWithOtpOptions, type TorrowAuthOtpFlowOptions, type TorrowAuthResult, type TorrowAuthSessionBase };