@owlmeans/web-auth-email 0.0.0-stage → 0.1.19

package/src/i18n/ru.json

@@ -0,0 +1,100 @@
+{
+  "captcha": {
+    "notice": "Этот сайт защищён reCAPTCHA, и к нему применяются {{privacy}} и {{terms}} Google.",
+    "privacy": "Политика конфиденциальности",
+    "terms": "Условия использования"
+  },
+  "error": {
+    "captcha": "Не удалось подтвердить, что вы не робот. Попробуйте ещё раз.",
+    "captcha-unavailable": "Не удалось загрузить проверку безопасности. Проверьте подключение и попробуйте ещё раз.",
+    "code": "Код неверный или устарел. Проверьте его или запросите новый.",
+    "credentials": "Неверный адрес электронной почты или пароль.",
+    "email": "Введите правильный адрес электронной почты.",
+    "failed": "Что-то пошло не так. Попробуйте ещё раз.",
+    "mismatch": "Пароли не совпадают.",
+    "offer-expired": "Срок действия предложения истёк. Пароль можно задать позже в настройках аккаунта.",
+    "password-disabled": "Вход по паролю здесь недоступен. Войдите с кодом.",
+    "password-empty": "Введите пароль.",
+    "pin-format": "Введите код из письма: {{length}} цифр.",
+    "throttled": "Слишком много попыток. Подождите немного и попробуйте снова.",
+    "throttled-in": "Слишком много попыток. Попробуйте снова {{when}}.",
+    "unavailable": "Вход временно недоступен. Попробуйте позже.",
+    "weak": "Используйте от {{min}} до {{max}} символов и не используйте свой адрес электронной почты."
+  },
+  "login": {
+    "change-email": "Изменить адрес",
+    "device": "Мы не узнаём это устройство. Введите код, который мы отправили вам на почту.",
+    "done": "Выполняем вход…",
+    "email-label": "Электронная почта",
+    "email-placeholder": "you@example.com",
+    "hide-password": "Скрыть пароль",
+    "options-failed": "Не удалось загрузить настройки входа.",
+    "other": "Другие способы входа",
+    "password-label": "Пароль",
+    "password-submit": "Войти",
+    "password-subtitle": "Войдите с помощью электронной почты и пароля.",
+    "pin-label": "Код из письма",
+    "pin-subtitle": "Код для входа ждёт вас в почте.",
+    "powered": "Работает на OwlMeans",
+    "resend": "Отправить новый код",
+    "retry": "Повторить",
+    "send": "Получить PIN-код для входа",
+    "sending": "Отправляем…",
+    "sent": "Мы отправили код для входа на {{email}}.",
+    "show-password": "Показать пароль",
+    "subtitle": "Мы пришлём код для входа на вашу почту. Впервые здесь? Тот же код создаст ваш аккаунт.",
+    "title": "Вход по электронной почте",
+    "use-password": "Уже задали пароль? Войдите с ним",
+    "use-pin": "Войти с кодом",
+    "verify": "Войти",
+    "verifying": "Выполняем вход…"
+  },
+  "offer": {
+    "description": "В следующий раз входите по почте и паролю, не дожидаясь кода.",
+    "hint": "От {{min}} до {{max}} символов.",
+    "later": "Пароль всегда можно задать позже в настройках аккаунта.",
+    "password-label": "Новый пароль",
+    "repeat-label": "Повторите пароль",
+    "save": "Сохранить пароль",
+    "saving": "Сохраняем…",
+    "skip": "Не сейчас",
+    "title": "Задайте пароль для быстрого входа"
+  },
+  "password": {
+    "action": {
+      "change": "Изменить пароль",
+      "remove": "Удалить пароль",
+      "set": "Задать пароль"
+    },
+    "cancel": "Отмена",
+    "confirm": "Подтвердить",
+    "confirming": "Сохраняем…",
+    "description": "Входите по электронной почте и паролю вместо кода.",
+    "devices": "На других устройствах при следующем входе понадобится код.",
+    "done": {
+      "change": "Пароль изменён.",
+      "remove": "Пароль удалён.",
+      "set": "Пароль задан."
+    },
+    "explain": {
+      "change": "Чтобы изменить пароль, подтвердите, что это вы, кодом, который мы пришлём на почту.",
+      "remove": "Без пароля вы входите с кодом, который приходит на почту. Мы пришлём код для подтверждения.",
+      "set": "Чтобы задать пароль, подтвердите, что это вы, кодом, который мы пришлём на почту."
+    },
+    "loading": "Загрузка…",
+    "new-label": "Новый пароль",
+    "off": "Вход по паролю здесь недоступен. Вы входите с кодом, который приходит на почту.",
+    "pin-label": "Код из письма",
+    "repeat-label": "Повторите пароль",
+    "resend": "Отправить новый код",
+    "retry": "Повторить",
+    "send": "Отправить код",
+    "sending": "Отправляем…",
+    "sent": "Мы отправили код на вашу почту.",
+    "set": "У вас есть пароль.",
+    "title": "Пароль",
+    "unreadable": "Не удалось загрузить настройки пароля.",
+    "unset": "У вас пока нет пароля. Вы входите с кодом, который приходит на почту.",
+    "updated": "Последнее изменение: {{date}}."
+  }
+}

package/src/i18n/uk.json

@@ -0,0 +1,100 @@
+{
+  "captcha": {
+    "notice": "Цей сайт захищено reCAPTCHA, і до нього застосовуються {{privacy}} та {{terms}} Google.",
+    "privacy": "Політика конфіденційності",
+    "terms": "Умови використання"
+  },
+  "error": {
+    "captcha": "Не вдалося підтвердити, що ви не робот. Спробуйте ще раз.",
+    "captcha-unavailable": "Не вдалося завантажити перевірку безпеки. Перевірте з'єднання та спробуйте ще раз.",
+    "code": "Код неправильний або застарів. Перевірте його або запросіть новий.",
+    "credentials": "Неправильна адреса електронної пошти або пароль.",
+    "email": "Введіть правильну адресу електронної пошти.",
+    "failed": "Щось пішло не так. Спробуйте ще раз.",
+    "mismatch": "Паролі не збігаються.",
+    "offer-expired": "Термін дії пропозиції минув. Пароль можна встановити пізніше в налаштуваннях облікового запису.",
+    "password-disabled": "Вхід за паролем тут недоступний. Увійдіть за кодом.",
+    "password-empty": "Введіть пароль.",
+    "pin-format": "Введіть код із листа: {{length}} цифр.",
+    "throttled": "Забагато спроб. Зачекайте трохи й спробуйте знову.",
+    "throttled-in": "Забагато спроб. Спробуйте знову {{when}}.",
+    "unavailable": "Вхід тимчасово недоступний. Спробуйте пізніше.",
+    "weak": "Використовуйте від {{min}} до {{max}} символів і не використовуйте свою адресу електронної пошти."
+  },
+  "login": {
+    "change-email": "Змінити адресу",
+    "device": "Ми не впізнаємо цей пристрій. Введіть код, який ми надіслали вам на пошту.",
+    "done": "Виконуємо вхід…",
+    "email-label": "Електронна пошта",
+    "email-placeholder": "you@example.com",
+    "hide-password": "Сховати пароль",
+    "options-failed": "Не вдалося завантажити налаштування входу.",
+    "other": "Інші способи входу",
+    "password-label": "Пароль",
+    "password-submit": "Увійти",
+    "password-subtitle": "Увійдіть за допомогою електронної пошти та пароля.",
+    "pin-label": "Код із листа",
+    "pin-subtitle": "Код для входу чекає на вас у пошті.",
+    "powered": "Працює на OwlMeans",
+    "resend": "Надіслати новий код",
+    "retry": "Повторити",
+    "send": "Отримати PIN-код для входу",
+    "sending": "Надсилаємо…",
+    "sent": "Ми надіслали код для входу на {{email}}.",
+    "show-password": "Показати пароль",
+    "subtitle": "Ми надішлемо код для входу на вашу пошту. Вперше тут? Той самий код створить ваш обліковий запис.",
+    "title": "Вхід за електронною поштою",
+    "use-password": "Уже встановили пароль? Увійдіть із ним",
+    "use-pin": "Увійти за кодом",
+    "verify": "Увійти",
+    "verifying": "Виконуємо вхід…"
+  },
+  "offer": {
+    "description": "Наступного разу входьте за поштою й паролем, не чекаючи на код.",
+    "hint": "Від {{min}} до {{max}} символів.",
+    "later": "Пароль завжди можна встановити пізніше в налаштуваннях облікового запису.",
+    "password-label": "Новий пароль",
+    "repeat-label": "Повторіть пароль",
+    "save": "Зберегти пароль",
+    "saving": "Зберігаємо…",
+    "skip": "Не зараз",
+    "title": "Встановіть пароль для швидкого входу"
+  },
+  "password": {
+    "action": {
+      "change": "Змінити пароль",
+      "remove": "Видалити пароль",
+      "set": "Встановити пароль"
+    },
+    "cancel": "Скасувати",
+    "confirm": "Підтвердити",
+    "confirming": "Зберігаємо…",
+    "description": "Входьте за електронною поштою та паролем замість коду.",
+    "devices": "На інших пристроях під час наступного входу знадобиться код.",
+    "done": {
+      "change": "Пароль змінено.",
+      "remove": "Пароль видалено.",
+      "set": "Пароль встановлено."
+    },
+    "explain": {
+      "change": "Щоб змінити пароль, підтвердьте, що це ви, кодом, який ми надішлемо на пошту.",
+      "remove": "Без пароля ви входите за кодом, який приходить на пошту. Ми надішлемо код для підтвердження.",
+      "set": "Щоб встановити пароль, підтвердьте, що це ви, кодом, який ми надішлемо на пошту."
+    },
+    "loading": "Завантаження…",
+    "new-label": "Новий пароль",
+    "off": "Вхід за паролем тут недоступний. Ви входите за кодом, який приходить на пошту.",
+    "pin-label": "Код із листа",
+    "repeat-label": "Повторіть пароль",
+    "resend": "Надіслати новий код",
+    "retry": "Повторити",
+    "send": "Надіслати код",
+    "sending": "Надсилаємо…",
+    "sent": "Ми надіслали код на вашу пошту.",
+    "set": "У вас є пароль.",
+    "title": "Пароль",
+    "unreadable": "Не вдалося завантажити налаштування пароля.",
+    "unset": "У вас ще немає пароля. Ви входите за кодом, який приходить на пошту.",
+    "updated": "Остання зміна: {{date}}."
+  }
+}

package/src/i18n.ts

@@ -0,0 +1,43 @@
+import { i18nHelper } from '@owlmeans/i18n'
+import { AUTH_I18N, EMAIL_AUTH_I18N } from './consts.js'
+
+import en from './i18n/en.json' with { type: 'json' }
+import pl from './i18n/pl.json' with { type: 'json' }
+import ru from './i18n/ru.json' with { type: 'json' }
+import be from './i18n/be.json' with { type: 'json' }
+import uk from './i18n/uk.json' with { type: 'json' }
+import es from './i18n/es.json' with { type: 'json' }
+import de from './i18n/de.json' with { type: 'json' }
+import fr from './i18n/fr.json' with { type: 'json' }
+
+import authEn from './i18n/auth/en.json' with { type: 'json' }
+import authPl from './i18n/auth/pl.json' with { type: 'json' }
+import authRu from './i18n/auth/ru.json' with { type: 'json' }
+import authBe from './i18n/auth/be.json' with { type: 'json' }
+import authUk from './i18n/auth/uk.json' with { type: 'json' }
+import authEs from './i18n/auth/es.json' with { type: 'json' }
+import authDe from './i18n/auth/de.json' with { type: 'json' }
+import authFr from './i18n/auth/fr.json' with { type: 'json' }
+
+i18nHelper.addI18nLib('en', EMAIL_AUTH_I18N, en)
+i18nHelper.addI18nLib('pl', EMAIL_AUTH_I18N, pl)
+i18nHelper.addI18nLib('ru', EMAIL_AUTH_I18N, ru)
+i18nHelper.addI18nLib('be', EMAIL_AUTH_I18N, be)
+i18nHelper.addI18nLib('uk', EMAIL_AUTH_I18N, uk)
+i18nHelper.addI18nLib('es', EMAIL_AUTH_I18N, es)
+i18nHelper.addI18nLib('de', EMAIL_AUTH_I18N, de)
+i18nHelper.addI18nLib('fr', EMAIL_AUTH_I18N, fr)
+
+/**
+ * The chooser button's label, `login.method.email`, pushed into the `auth` library resource that
+ * `@owlmeans/client-auth/login` fills with the rest of the sign-in screen — the bundles merge by
+ * tier and priority, exactly as `@owlmeans/web-panel` adds `login.provider.*`.
+ */
+i18nHelper.addI18nLib('en', AUTH_I18N, authEn)
+i18nHelper.addI18nLib('pl', AUTH_I18N, authPl)
+i18nHelper.addI18nLib('ru', AUTH_I18N, authRu)
+i18nHelper.addI18nLib('be', AUTH_I18N, authBe)
+i18nHelper.addI18nLib('uk', AUTH_I18N, authUk)
+i18nHelper.addI18nLib('es', AUTH_I18N, authEs)
+i18nHelper.addI18nLib('de', AUTH_I18N, authDe)
+i18nHelper.addI18nLib('fr', AUTH_I18N, authFr)

package/src/index.ts

@@ -0,0 +1,22 @@
+export * from './consts.js'
+export type * from './types.js'
+export * from './utils.js'
+export * from './state.js'
+export type * from './state/types.js'
+export * from './refusal.js'
+export type * from './refusal/types.js'
+export * from './storage.js'
+export type * from './storage/types.js'
+export * from './password.js'
+export type * from './password/types.js'
+export * from './service.js'
+export * from './step.js'
+export * from './plugin.js'
+export * from './append.js'
+export * from './entrypoints.js'
+export * from './hooks/use-email-login.js'
+export * from './hooks/use-password.js'
+export * from './hooks/use-translate.js'
+export type * from './hooks/types.js'
+export * from './components/index.js'
+export * from './i18n.js'

package/src/password/types.ts

@@ -0,0 +1,43 @@
+import type { EmailPasswordPurpose, EmailPasswordStatusView } from '@owlmeans/auth-email'
+import type { EmailRefusal } from '../refusal/types.js'
+
+/** What a person can do with their password from the panel. */
+export type EmailPasswordAction = 'set' | 'change' | 'remove'
+
+/**
+ * What the panel shows: the status is still loading, could not be read, passwords are off on this
+ * deployment, or the account has no password / has one.
+ */
+export type PasswordPanelState = 'loading' | 'unreadable' | 'off' | 'unset' | 'set'
+
+/** The panel's own fields while an action is open. */
+export interface PasswordPanelForm {
+  pin: string
+  password: string
+  repeat: string
+}
+
+/** The policy a new password is checked against before it is sent. */
+export interface PasswordPolicy {
+  minLength?: number
+  maxLength?: number
+  pinLength?: number
+}
+
+/** The password panel and the offer step as pure decisions — no React, no I/O. */
+export interface PasswordPanelHelper {
+  stateOf: (status: EmailPasswordStatusView | null, loading: boolean) => PasswordPanelState
+  /** The actions offered for a status: `set` without a password, `change` + `remove` with one. */
+  actionsOf: (status: EmailPasswordStatusView | null) => EmailPasswordAction[]
+  /** The confirmation PIN's purpose for an action — what `password/pin` is asked for. */
+  purposeOf: (action: EmailPasswordAction) => EmailPasswordPurpose
+  /** Whether the action asks for a new password (set, change) or only a PIN (remove). */
+  needsPassword: (action: EmailPasswordAction) => boolean
+  /**
+   * What stops a new password from being sent: empty, outside the length bounds (NFKC, as the
+   * server counts), or not repeated exactly. Null when it may go.
+   */
+  passwordBlock: (password: string, repeat: string, policy?: PasswordPolicy) => EmailRefusal | null
+  /** What stops "Confirm" for an action: the PIN's format first, then the new password. */
+  confirmBlock: (action: EmailPasswordAction, form: PasswordPanelForm, policy?: PasswordPolicy) => EmailRefusal | null
+}

package/src/password.ts

@@ -0,0 +1,65 @@
+import {
+  EMAIL_PASSWORD_MAX_LENGTH, EMAIL_PASSWORD_MIN_LENGTH, EMAIL_PIN_LENGTH, EmailPasswordPurpose,
+} from '@owlmeans/auth-email'
+import type { EmailPasswordStatusView } from '@owlmeans/auth-email'
+import type { EmailRefusal } from './refusal/types.js'
+import type {
+  EmailPasswordAction, PasswordPanelForm, PasswordPanelHelper, PasswordPanelState, PasswordPolicy,
+} from './password/types.js'
+
+export const createPasswordPanelHelper = (): PasswordPanelHelper => {
+  const stateOf = (status: EmailPasswordStatusView | null, loading: boolean): PasswordPanelState => {
+    if (status == null) {
+      return loading ? 'loading' : 'unreadable'
+    }
+    if (!status.enabled) {
+      return 'off'
+    }
+
+    return status.set ? 'set' : 'unset'
+  }
+
+  const actionsOf = (status: EmailPasswordStatusView | null): EmailPasswordAction[] => {
+    switch (stateOf(status, false)) {
+      case 'set':
+        return ['change', 'remove']
+      case 'unset':
+        return ['set']
+      default:
+        return []
+    }
+  }
+
+  const purposeOf = (action: EmailPasswordAction): EmailPasswordPurpose =>
+    action === 'set' ? EmailPasswordPurpose.Set
+      : action === 'change' ? EmailPasswordPurpose.Change : EmailPasswordPurpose.Remove
+
+  const needsPassword = (action: EmailPasswordAction): boolean => action !== 'remove'
+
+  const passwordBlock = (password: string, repeat: string, policy?: PasswordPolicy): EmailRefusal | null => {
+    if (password === '') {
+      return { kind: 'password-empty' }
+    }
+    const length = password.normalize('NFKC').length
+    if (length < (policy?.minLength ?? EMAIL_PASSWORD_MIN_LENGTH)
+      || length > (policy?.maxLength ?? EMAIL_PASSWORD_MAX_LENGTH)) {
+      return { kind: 'weak' }
+    }
+
+    return password === repeat ? null : { kind: 'mismatch' }
+  }
+
+  const confirmBlock = (
+    action: EmailPasswordAction, form: PasswordPanelForm, policy?: PasswordPolicy
+  ): EmailRefusal | null => {
+    if (!new RegExp(`^[0-9]{${policy?.pinLength ?? EMAIL_PIN_LENGTH}}$`).test(form.pin)) {
+      return { kind: 'pin-format' }
+    }
+
+    return needsPassword(action) ? passwordBlock(form.password, form.repeat, policy) : null
+  }
+
+  return { stateOf, actionsOf, purposeOf, needsPassword, passwordBlock, confirmBlock }
+}
+
+export const passwordPanelHelper = createPasswordPanelHelper()

package/src/plugin.ts

@@ -0,0 +1,22 @@
+import type { AuthenticationPlugin, AuthMethodMeta } from '@owlmeans/client-auth/manager/plugins'
+import { EMAIL_LOGIN_METHOD, EMAIL_LOGIN_SERVICE } from '@owlmeans/auth-email'
+import { EMAIL_LOGIN_METHOD_META } from './consts.js'
+import { EmailLoginRoute } from './components/route.js'
+
+/**
+ * The `email` authentication plugin: a self-contained method whose route
+ * (`/authentication/login/email`) renders the e-mail card and completes the sign-in itself.
+ *
+ * It needs no renderer, and it is offered only where `appendEmailLogin` registered the client
+ * service — so a bundle that merely contains this package never grows a button that cannot work.
+ */
+export const makeEmailLoginPlugin = (method?: Partial<AuthMethodMeta>): AuthenticationPlugin => ({
+  type: EMAIL_LOGIN_METHOD,
+  requiresRenderer: false,
+  method: {
+    ...EMAIL_LOGIN_METHOD_META,
+    ...method,
+    available: ctx => ctx.context.hasService(EMAIL_LOGIN_SERVICE),
+  },
+  Implementation: () => EmailLoginRoute,
+})

package/src/refusal/consts.local.ts

@@ -0,0 +1,2 @@
+/** `CaptchaLoadError`'s `name` — recognised by name too, since a second copy of the class fails `instanceof`. */
+export const CAPTCHA_LOAD_ERROR = 'CaptchaLoadError'

package/src/refusal/types.ts

@@ -0,0 +1,64 @@
+import type { Translate } from '../types.js'
+
+/**
+ * Why an e-mail sign-in or password action did not go through, as the person is told.
+ *
+ * Server refusals (`throttled`, `code`, `credentials`, `captcha`, `captcha-unavailable`,
+ * `unavailable`, `weak`, `offer-expired`, `password-disabled`, `failed`) are read from the error a
+ * call rejected with; the rest (`email`, `pin-format`, `password-empty`, `mismatch`, and `weak` for a
+ * length the policy refuses anyway) are found before anything is sent.
+ */
+export type EmailRefusalKind =
+  | 'throttled'
+  | 'code'
+  | 'credentials'
+  | 'captcha'
+  | 'captcha-unavailable'
+  | 'unavailable'
+  | 'email'
+  | 'pin-format'
+  | 'password-empty'
+  | 'mismatch'
+  | 'weak'
+  | 'offer-expired'
+  | 'password-disabled'
+  | 'failed'
+
+/**
+ * Which call was refused — the same status means different things on different calls: a 401 is a
+ * wrong code after a PIN and a wrong password after a password sign-in.
+ */
+export type EmailRefusalContext =
+  | 'options'
+  | 'send'
+  | 'pin'
+  | 'password'
+  | 'status'
+  | 'confirm'
+  | 'set'
+  | 'remove'
+  | 'offer'
+
+export interface EmailRefusal {
+  kind: EmailRefusalKind
+  /** Seconds until a throttled request may be repeated, when the refusal said so. */
+  retryAfter?: number
+}
+
+/** Reads a failed call as a refusal and phrases it. */
+export interface EmailRefusalHelper {
+  /**
+   * The refusal an error stands for.
+   *
+   * A development server sends the typed error (`AuthenFailed('email:password')`, `OtpThrottled`,
+   * `EmailPasswordWeak`, `AuthenFailed('recaptcha:score')`…); a production one only the HTTP status
+   * and an incident id. Both are read — the type first, then the status in the light of `context` —
+   * and anything unrecognised is `failed`, never a guess.
+   */
+  refusalOf: (error: unknown, context: EmailRefusalContext) => EmailRefusal
+  /**
+   * The sentence for a refusal in the reader's language. `locale` formats a known waiting time
+   * ("in 45 seconds") with `Intl.RelativeTimeFormat`, so no plural rule lives in a translation.
+   */
+  messageOf: (refusal: EmailRefusal, t: Translate, locale?: string) => string
+}

package/src/refusal.ts

@@ -0,0 +1,145 @@
+import { apiStatusHelper } from '@owlmeans/api'
+import {
+  EMAIL_PASSWORD_MAX_LENGTH, EMAIL_PASSWORD_MIN_LENGTH, EMAIL_PIN_LENGTH, EmailAuthUnavailable,
+  EmailOfferExpired, EmailPasswordDisabled, EmailPasswordWeak,
+} from '@owlmeans/auth-email'
+import { CaptchaLoadError } from '@owlmeans/web-captcha'
+import type { Translate } from './types.js'
+import type { EmailRefusal, EmailRefusalContext, EmailRefusalHelper } from './refusal/types.js'
+import { textUtils } from './utils/text.js'
+import { CAPTCHA_LOAD_ERROR } from './refusal/consts.local.js'
+
+export const createEmailRefusalHelper = (): EmailRefusalHelper => {
+  /** Everything an error says about itself: its registered type and its message. */
+  const textOf = (error: unknown): string => {
+    if (error == null || typeof error !== 'object') {
+      return typeof error === 'string' ? error : ''
+    }
+    const { type, message, name } = error as { type?: unknown, message?: unknown, name?: unknown }
+
+    return [type, name, message].filter(value => typeof value === 'string').join(' ')
+  }
+
+  /**
+   * Seconds to wait, when the error carries them. An `OtpThrottled` rebuilt from a development
+   * body states 1 whatever the server said (the number is not on the wire), so only a longer wait
+   * is believed; otherwise the sentence names no time at all.
+   */
+  const retryAfterOf = (error: unknown): number | undefined => {
+    const value = error != null && typeof error === 'object'
+      ? (error as { retryAfter?: unknown }).retryAfter : undefined
+
+    return typeof value === 'number' && Number.isFinite(value) && value > 1 ? Math.ceil(value) : undefined
+  }
+
+  const refusalOf = (error: unknown, context: EmailRefusalContext): EmailRefusal => {
+    const text = textOf(error)
+    const status = apiStatusHelper.httpStatusOf(error)
+
+    if (error instanceof CaptchaLoadError || text.includes(CAPTCHA_LOAD_ERROR)) {
+      // The browser could not get a token at all — the script did not load or Google gave none.
+      return { kind: 'captcha-unavailable' }
+    }
+    if (status === 429 || /Throttled|:throttled/.test(text)) {
+      const retryAfter = retryAfterOf(error)
+      return retryAfter != null ? { kind: 'throttled', retryAfter } : { kind: 'throttled' }
+    }
+    if (text.includes('recaptcha')) {
+      return { kind: status === 503 || text.includes('Unavailable') ? 'captcha-unavailable' : 'captcha' }
+    }
+    if (text.includes(EmailPasswordWeak.typeName) || status === 422) {
+      return { kind: 'weak' }
+    }
+    if (text.includes(EmailOfferExpired.typeName) || status === 409) {
+      return { kind: 'offer-expired' }
+    }
+    if (text.includes(EmailPasswordDisabled.typeName)) {
+      return { kind: 'password-disabled' }
+    }
+    if (text.includes('email:password')) {
+      return { kind: 'credentials' }
+    }
+    if (/otp:(code|email)|authen:challenge|email:confirm/.test(text)) {
+      return { kind: 'code' }
+    }
+    if (status === 503 || text.includes(EmailAuthUnavailable.typeName) || text.includes('Unavailable')) {
+      return { kind: 'unavailable' }
+    }
+
+    // A production body carries nothing but the status (and the server's own refusal classes are
+    // not registered here, so a development one often arrives the same way): read it in the light
+    // of the call. A credential refused on a guest route is 401; a captcha or a confirmation PIN
+    // refused is 403 — never 401 on a signed-in route, which would drop the session.
+    switch (status) {
+      case 403:
+        return { kind: context === 'send' || context === 'password' ? 'captcha'
+          : context === 'pin' || context === 'confirm' || context === 'set' || context === 'remove' ? 'code' : 'failed' }
+      case 401:
+        return { kind: context === 'password' ? 'credentials' : context === 'pin' || context === 'confirm'
+          || context === 'set' || context === 'remove' ? 'code' : 'failed' }
+      case 404:
+        return { kind: context === 'password' || context === 'status' || context === 'confirm'
+          || context === 'set' || context === 'remove' || context === 'offer' ? 'password-disabled' : 'failed' }
+      case 400:
+        return { kind: context === 'send' ? 'email' : 'failed' }
+      default:
+        return { kind: 'failed' }
+    }
+  }
+
+  /** "in 45 seconds", "через 2 минуты" — the language's own plural rules, never a translation's. */
+  const waitOf = (seconds: number, locale?: string): string => {
+    const minutes = seconds >= 90
+    const value = minutes ? Math.ceil(seconds / 60) : seconds
+    try {
+      return new Intl.RelativeTimeFormat(locale, { numeric: 'always' }).format(value, minutes ? 'minute' : 'second')
+    } catch {
+      return `${value} ${minutes ? 'min' : 's'}`
+    }
+  }
+
+  const messageOf = (refusal: EmailRefusal, t: Translate, locale?: string): string => {
+    switch (refusal.kind) {
+      case 'throttled':
+        return refusal.retryAfter != null
+          ? textUtils.fill(t('error.throttled-in', 'Too many attempts. Please try again {{when}}.'), {
+            when: waitOf(refusal.retryAfter, locale),
+          })
+          : t('error.throttled', 'Too many attempts. Please wait a little and try again.')
+      case 'code':
+        return t('error.code', 'This code is wrong or has expired. Check it or ask for a new one.')
+      case 'credentials':
+        return t('error.credentials', 'Wrong email or password.')
+      case 'captcha':
+        return t('error.captcha', "We couldn't confirm that you're not a robot. Please try again.")
+      case 'captcha-unavailable':
+        return t('error.captcha-unavailable', "The security check couldn't load. Check your connection and try again.")
+      case 'unavailable':
+        return t('error.unavailable', 'Sign-in is temporarily unavailable. Please try again later.')
+      case 'email':
+        return t('error.email', 'Enter a valid email address.')
+      case 'pin-format':
+        return textUtils.fill(t('error.pin-format', 'Enter the code from the email: {{length}} digits.'), {
+          length: EMAIL_PIN_LENGTH,
+        })
+      case 'password-empty':
+        return t('error.password-empty', 'Enter your password.')
+      case 'mismatch':
+        return t('error.mismatch', "The passwords don't match.")
+      case 'weak':
+        return textUtils.fill(t('error.weak', 'Use {{min}} to {{max}} characters, and not your email address.'), {
+          min: EMAIL_PASSWORD_MIN_LENGTH, max: EMAIL_PASSWORD_MAX_LENGTH,
+        })
+      case 'offer-expired':
+        return t('error.offer-expired', 'This offer has expired. You can set a password later in your account settings.')
+      case 'password-disabled':
+        return t('error.password-disabled', 'Password sign-in is not available here. Use a code instead.')
+      default:
+        return t('error.failed', 'Something went wrong. Please try again.')
+    }
+  }
+
+  return { refusalOf, messageOf }
+}
+
+export const emailRefusalHelper = createEmailRefusalHelper()