@torrow/sdk-auth 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,320 @@
-# 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 -->|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`**.
+
+## Целевой клиентский код
+
+Общая база `{ 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.

package/dist/index.d.ts

@@ -0,0 +1,350 @@
+import { T as TokenStorage, A as AuthTokenSnapshot, a as TokenSessionOptions, b as TokenSessionStatus, c as TokenSessionStatusListener } from './types-LCuPy3dY.js';
+export { d as AppCredentials, D as DEFAULT_APP_CREDENTIALS, R as RefreshFailureAction } from './types-LCuPy3dY.js';
+import { TorrowClient, DeviceInfo, TokenResp, AuthScope, VerificationMethod, SendCodeAccountType, AuthCaptchaType, AccountType } from '@torrow/sdk-client';
+
+/**
+ * In-memory реализация {@link TokenStorage}.
+ *
+ * Тесты, эфемерные процессы, `TorrowAuth.fromTokens` без диска.
+ * Для Node-примеров обычно {@link FileTokenStorage}; для браузера —
+ * {@link LocalStorageTokenStorage}.
+ */
+
+/** In-memory хранилище токенов сессии. */
+declare class MemoryTokenStorage implements TokenStorage {
+    private snapshot;
+    constructor(initial?: AuthTokenSnapshot);
+    load(): Promise<AuthTokenSnapshot>;
+    save(snapshot: AuthTokenSnapshot): Promise<void>;
+}
+
+/**
+ * Persist snapshot в браузерный **`localStorage`** — реализация {@link TokenStorage}.
+ *
+ * Для виджетов / SPA (`TorrowAuth.fromTokens` / `connect`). В Node без
+ * `globalThis.localStorage` конструктор бросит. Не путать с {@link FileTokenStorage}.
+ */
+
+type LocalStorageLike = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
+};
+/**
+ * Persist snapshot токенов в браузерный `localStorage` (виджет / SPA).
+ */
+declare class LocalStorageTokenStorage implements TokenStorage {
+    readonly key: string;
+    private readonly store;
+    constructor(key: string, store?: LocalStorageLike);
+    load(): Promise<AuthTokenSnapshot>;
+    save(snapshot: AuthTokenSnapshot): Promise<void>;
+}
+
+/** Сессия auth ещё не подтверждена (например Telegram до Start у бота). */
+declare class AuthSessionNotReadyError extends Error {
+    readonly name = "AuthSessionNotReadyError";
+    readonly cause?: unknown;
+    constructor(message?: string, cause?: unknown);
+}
+
+/**
+ * Ядро пользовательской сессии: persist + проактивный refresh + single-flight + 401-retry.
+ *
+ * Low-level API: {@link TokenSession.open}. Канон для приложений —
+ * **`TorrowAuth.connect` / `login*` / `fromTokens`** (см. `torrow-auth.ts`).
+ *
+ * Логин снаружи: `TorrowAuth.loginWithOtp` / `loginWithLink`, либо
+ * `requestTokenWithCode` / `applyTokenResp` на уже открытой сессии.
+ * Не путать статус `"unauthenticated"` с `TorrowAuth.anonymous` (клиент без сессии).
+ */
+
+/**
+ * Пользовательская сессия (класс). См. file overview выше.
+ */
+declare class TokenSession {
+    private readonly opts;
+    private tokenSnapshot;
+    private ensureFreshMutex;
+    private _client;
+    private readonly statusListeners;
+    private closed;
+    /** Set in refreshWithFailurePolicy catch; not cleared on success (see public refresh). */
+    private lastRefreshError;
+    private constructor();
+    static open(opts: TokenSessionOptions): Promise<TokenSession>;
+    /** Persist, переданный в `TokenSession.open` / `TorrowAuth.*`. */
+    get tokenStorage(): TokenStorage;
+    get client(): TorrowClient;
+    /** Текущий статус сессии. */
+    get status(): TokenSessionStatus;
+    /** Подписка на смену статуса; возвращает unsubscribe. Сразу вызывает listener с текущим статусом. */
+    onStatusChange(listener: TokenSessionStatusListener): () => void;
+    /** Текущий снимок токенов сессии (копия {@link AuthTokenSnapshot}). */
+    getTokenSnapshot(): AuthTokenSnapshot;
+    /** `deviceInfo` из options open или fallback Desktop + deviceId из tokenSnapshot. */
+    getDeviceInfo(): DeviceInfo;
+    getAccessToken(): Promise<string | undefined>;
+    /**
+     * Сохранить ответ `requestToken` / `refresh` (только TokenReady).
+     * Сериализован с `ensureFresh` / `logout` через mutex. Дефолт merge намеренно
+     * (refresh-shaped); логин — `{ replace: true }`. После `logout` — новая сессия.
+     */
+    applyTokenResp(tokens: TokenResp, opts?: {
+        replace?: boolean;
+    }): Promise<void>;
+    clearTokens(): Promise<void>;
+    /**
+     * Revoke refresh (если есть) + очистка storage.
+     * Единственное публичное имя выхода из сессии.
+     */
+    logout(): Promise<void>;
+    /**
+     * Получить токены по **id auth-сессии** (`sessionId` из `sendCode` / `createSession`)
+     * и **OTP-коду доступа**, затем сохранить их в storage сессии.
+     *
+     * Один вызов `POST /api/v1/auth/token` (`requestToken`) с `{ sessionId, code }`.
+     * При успехе (`TokenReady`) — persist; если сессия ещё не готова —
+     * {@link AuthSessionNotReadyError} (поллинг для deep-link — внутри `TorrowAuth.loginWithLink`).
+     *
+     * HTTP вне mutex; persist сериализован через {@link applyTokenResp} (не оборачивать
+     * весь метод в `runExclusive` — вложенный mutex с публичным `applyTokenResp`).
+     */
+    requestTokenWithCode(args: {
+        sessionId: string;
+        code: string;
+        scopes?: AuthScope[];
+        signal?: AbortSignal;
+    }): Promise<TokenResp>;
+    /**
+     * Явный refresh (single-flight через общий mutex сессии).
+     * Сериализован с `logout` / `ensureFresh` / `applyTokenResp`.
+     * При гонке с `logout()`: promise может resolve с `TokenResp`, но snapshot уже очищен —
+     * не используй return value; смотри `session.status` / `getTokenSnapshot()`.
+     */
+    refresh(): Promise<TokenResp>;
+    ensureFresh(): Promise<void>;
+    private assertNotClosedForWrite;
+    /** Caller must hold `runExclusive`. Do not call public `applyTokenResp` from here. */
+    private applyTokenRespUnlocked;
+    private clearTokensUnlocked;
+    /** Caller must hold `runExclusive`. `refreshWithFailurePolicy` skips when no refreshToken; guard here is intentional defense-in-depth. */
+    private refreshUnlocked;
+    /** Caller must hold `runExclusive`. */
+    private refreshWithFailurePolicy;
+    private runExclusive;
+    private ensureFreshImpl;
+    private isAccessStillFresh;
+    private computeStatus;
+    private emitStatusChange;
+    private resolveDeviceInfo;
+    /** Identity-клиент с Basic приложения, без Bearer пользователя. */
+    identityClient(): TorrowClient;
+    private buildClient;
+    private persist;
+}
+
+/**
+ * Внутренний оркестратор OTP-логина (не публичный export целиком; типы UI — да).
+ *
+ * **`sendCode`** → ветка по **`usedMethod`** (Mobile ID poll | classic код) →
+ * **`TokenResp`**. UI снаружи: **`onSendCode`** + **`getCode`**.
+ * IMAP / stdin / env — в app / `examples/node/_shared`, не здесь.
+ *
+ * Вызывается из `TorrowAuth.loginWithOtp`; Mobile ID — `mobile-id.ts`.
+ */
+
+/**
+ * Аргумент **`onSendCode`**: снимок **после** успешного `sendCode` (в основном поля **`SendCodeResp`**).
+ * Не путать с телом запроса: в `sendCode` уходят `supportedMethods` / `preferredMethod`
+ * (см. {@link RunOtpLoginOptions}); здесь — что сервер **выбрал** и что ещё доступно.
+ *
+ * Типичный UI: по `usedMethod` показать «ждём SMS» / «код на email» / «подтвердите push»;
+ * по `codeLength` — маску поля ввода.
+ */
+type OtpSendCodeResult = {
+    /** Аккаунт из `SendCodeReq` (телефон / email). */
+    accountName: string;
+    /** `Phone` \| `Email` из запроса (не путать с `usedMethod`). */
+    accountType: SendCodeAccountType;
+    /** Id auth-сессии для последующего `requestToken` / Mobile ID poll. */
+    sessionId: string;
+    /**
+     * Фактический канал из **`SendCodeResp.usedMethod`** — ради этого и нужен `onSendCode`.
+     * Sms / Email / FlashCall / TelegramGateway / MtsMobileId / …
+     */
+    usedMethod?: VerificationMethod;
+    /** Длина кода для input/маски; у Mobile ID часто `0` (keypad не нужен). */
+    codeLength?: number;
+    /** Интервал poll при Mobile ID (`SendCodeResp.pollIntervalSeconds`). */
+    pollIntervalSeconds?: number;
+    /**
+     * Из **`SendCodeResp`** (не тело `sendCode`): методы, доступные для этого аккаунта
+     * (UX «другой способ»). В запрос передаётся {@link RunOtpLoginOptions.supportedMethods}.
+     */
+    availableMethods?: VerificationMethod[] | null;
+    /** TTL auth-сессии `sendCode` (сек); для Mobile ID — ориентир max wait. */
+    sessionLifeTimeInSeconds?: number;
+    /** Когда снова можно дернуть `sendCode` (rate-limit hint из ответа). */
+    nextAvailableUsageTime?: Date | null;
+};
+/**
+ * Аргумент **`getCode`**: только когда нужны цифры (stdin / UI / IMAP снаружи).
+ *
+ * UI-экран уже выбран в **`onSendCode`** (`usedMethod`). Здесь — собрать код
+ * (длина из `codeLength`). На happy-path Mobile ID (push) **`getCode` не вызывается**;
+ * SMS-fallback после poll — тот же колбэк, без отдельного `reason`.
+ *
+ * `accountName` / `accountType` не дублируются — они в options и в `onSendCode`.
+ */
+type OtpGetCodeContext = {
+    sessionId: string;
+    /** Эффективная длина для валидации (Mobile ID SMS fallback: при `0` с сервера → 4). */
+    codeLength?: number;
+    /** Канал из `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);
+}
+
+/**
+ * Публичный фасад аутентификации **`TorrowAuth`**.
+ *
+ * Точка входа приложения: `connect` / `loginWithOtp` / `loginWithLink` /
+ * `fromTokens` / `anonymous`. Возвращает {@link TorrowAuthResult}
+ * (`{ client, session }`), кроме `anonymous` (только `TorrowClient`).
+ *
+ * Оркестрация OTP/Telegram — в `otp-login.ts` / `link-login.ts`;
+ * persist и refresh — в {@link TokenSession}.
+ */
+
+/** Результат `TorrowAuth.connect` / `loginWithOtp` / `loginWithLink` / `fromTokens`: API-клиент + сессия. */
+type TorrowAuthResult = {
+    client: TorrowClient;
+    session: TokenSession;
+};
+/**
+ * Общая база опций `TorrowAuth.connect` / `loginWithOtp` / `loginWithLink` / `fromTokens`.
+ *
+ * Производная от {@link TokenSessionOptions}: те же HTTP-кнопки + storage + app creds,
+ * но `deviceInfo` **обязателен**; `onRefreshFailure` пробрасывается в `TokenSession.open`.
+ *
+ * **Карта:** `TorrowClientConfig` → (Pick HTTP) → `TokenSessionOptions` → **эта база** →
+ * `TorrowAuthConnectOptions` / `TorrowAuthLoginWithOtpOptions` / …
+ * Приложение обычно передаёт именно `TorrowAuth*Options`, не `TorrowClientConfig`.
+ *
+ * `appCredentials` опционален: без него — дефолт SDK (`DEFAULT_APP_CREDENTIALS`).
+ */
+type TorrowAuthSessionBase = Omit<TokenSessionOptions, "deviceInfo"> & {
+    deviceInfo: DeviceInfo;
+};
+/** Опции {@link TorrowAuth.connect}: restore / refresh из `tokenStorage`. */
+type TorrowAuthConnectOptions = TorrowAuthSessionBase;
+/** Аккаунт для OTP `sendCode` — плоско, как OpenAPI `SendCodeReq`. */
+type TorrowAuthAccount = {
+    /** `Phone` \| `Email` → `SendCodeReq.type`. */
+    accountType: SendCodeAccountType;
+    /** Телефон или email → `SendCodeReq.accountName`. */
+    accountName: string;
+};
+/** Опции {@link TorrowAuth.loginWithOtp}: connect-база + OTP-колбэки / поля `sendCode`. */
+type TorrowAuthLoginWithOtpOptions = TorrowAuthSessionBase & {
+    account: TorrowAuthAccount;
+    /**
+     * Сигнал UI после `sendCode` (`usedMethod`, `codeLength`, …).
+     * До Mobile ID poll и до classic `getCode`. См. {@link OtpSendCodeResult}.
+     */
+    onSendCode: (result: OtpSendCodeResult) => void | Promise<void>;
+    /**
+     * Вернуть одноразовый код. Не зовётся на happy-path Mobile ID (push без SMS).
+     * См. {@link OtpGetCodeContext}.
+     */
+    getCode: (ctx: OtpGetCodeContext) => Promise<string>;
+    /** → `TokenReq.scopes`. По умолчанию `DefaultAuthScopes`. */
+    scopes?: AuthScope[];
+    /** → `SendCodeReq.language`. По умолчанию `"ru"`. */
+    language?: string;
+    /** → `SendCodeReq.regionStorageId`. По умолчанию `70`. */
+    regionStorageId?: number;
+    /** → `SendCodeReq.captcha` (если шлюз требует). */
+    captcha?: string;
+    /** → `SendCodeReq.captchaType`. */
+    captchaType?: AuthCaptchaType;
+    /** → `SendCodeReq.inviteSessionId`. */
+    inviteSessionId?: string;
+    /**
+     * Hint серверу → `SendCodeReq.preferredMethod`.
+     * Факт смотри в `onSendCode.usedMethod`.
+     */
+    preferredMethod?: VerificationMethod;
+    /**
+     * Capability клиента → `SendCodeReq.supportedMethods`.
+     * Без `MtsMobileId` сервер обычно не выберет Mobile ID.
+     */
+    supportedMethods?: VerificationMethod[];
+    /** Отмена `sendCode` / poll / `requestToken`. */
+    signal?: AbortSignal;
+};
+/** Опции {@link TorrowAuth.loginWithLink} (Telegram deep-link). */
+type TorrowAuthLoginWithLinkOptions = TorrowAuthSessionBase & {
+    /** Показать deep-link / QR (`CreateAuthSessionResp.authUrl`). */
+    onLink: (authUrl: string) => void | Promise<void>;
+    /** По умолчанию `Telegram`. */
+    accountType?: AccountType;
+    language?: string;
+    regionStorageId?: number;
+    captcha?: string;
+    inviteSessionId?: string;
+    scopes?: AuthScope[];
+    /** Интервал poll `requestToken` (мс). По умолчанию 2000. */
+    pollIntervalMs?: number;
+    /** Max wait poll (сек). Иначе TTL сессии из ответа или 180. */
+    pollTimeoutSec?: number;
+    signal?: AbortSignal;
+};
+/** Опции {@link TorrowAuth.fromTokens}: сид токенов от хоста в `tokenStorage` → connect. */
+type TorrowAuthFromTokensOptions = TorrowAuthSessionBase & {
+    accessToken: string;
+    /** Без него refresh недоступен (даже если задан `appCredentials`). */
+    refreshToken?: string;
+    /**
+     * Абсолютное истечение access (мс). Для opaque/integration keys без JWT `exp`.
+     * Приоритет **записи в snapshot**: explicit (`> 0` finite) → JWT `exp` → `undefined` (бессрочный ключ).
+     * Runtime freshness AND-ит JWT `exp`: будущий explicit TTL не оживит просроченный JWT.
+     * Opaque без JWT-формы: explicit TTL или бессрочно без TTL.
+     */
+    accessExpiresAtMs?: number;
+};
+/**
+ * Фасад аутентификации для приложений и виджетов.
+ *
+ * - {@link TorrowAuth.connect} — restore / refresh
+ * - {@link TorrowAuth.loginWithOtp} — OTP (Phone/Email, Mobile ID / classic)
+ * - {@link TorrowAuth.loginWithLink} — Telegram deep-link
+ * - {@link TorrowAuth.fromTokens} — сид токенов от хоста
+ * - {@link TorrowAuth.anonymous} — клиент без Bearer
+ */
+declare const TorrowAuth: {
+    readonly connect: (options: TorrowAuthConnectOptions) => Promise<TorrowAuthResult>;
+    readonly loginWithOtp: (options: TorrowAuthLoginWithOtpOptions) => Promise<TorrowAuthResult>;
+    readonly loginWithLink: (options: TorrowAuthLoginWithLinkOptions) => Promise<TorrowAuthResult>;
+    readonly fromTokens: (options: TorrowAuthFromTokensOptions) => Promise<TorrowAuthResult>;
+    readonly anonymous: (config?: Pick<TokenSessionOptions, "baseUrl" | "fetch" | "defaultHeaders" | "userAgent">) => TorrowClient;
+};
+
+export { AuthSessionNotReadyError, AuthTokenSnapshot, LocalStorageTokenStorage, MemoryTokenStorage, OtpAuthHeaderMissingError, OtpCodeRequestLimitExceededError, type OtpGetCodeContext, type OtpSendCodeResult, TokenSession, TokenSessionOptions, TokenSessionStatus, TokenSessionStatusListener, TokenStorage, TorrowAuth, type TorrowAuthAccount, type TorrowAuthConnectOptions, type TorrowAuthFromTokensOptions, type TorrowAuthLoginWithLinkOptions, type TorrowAuthLoginWithOtpOptions, type TorrowAuthResult, type TorrowAuthSessionBase };