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

package/src/service.ts

@@ -0,0 +1,95 @@
+import { createLazyService } from '@owlmeans/context'
+import type { AuthService } from '@owlmeans/auth-common'
+import { DEFAULT_ALIAS as AUTH_SERVICE } from '@owlmeans/client-auth'
+import { loginLandingOf } from '@owlmeans/client-auth/login'
+import type { ClientConfig } from '@owlmeans/client-context'
+import { EMAIL_LOGIN_SERVICE, EmailAuthError } from '@owlmeans/auth-email'
+import type { EmailAuthEntrypoints, EmailAuthOptionsView } from '@owlmeans/auth-email'
+import { emailStorageHelper } from './storage.js'
+import { signedInAccount } from './utils/account.js'
+import type {
+  EmailLoginClientContext, EmailLoginClientService, EmailLoginScreenComponent, MakeEmailLoginClientOptions,
+} from './types.js'
+
+/**
+ * Build the browser-side `EmailLoginClientService` over one protocol tree.
+ *
+ * Every call goes through `ctx.entrypoint(protocol)`, so the application binds the API routes
+ * itself (`bindAll`) — the same split as marketing consent's client.
+ */
+export const makeEmailLoginClient = (
+  protocols: EmailAuthEntrypoints, opts: MakeEmailLoginClientOptions = {},
+): EmailLoginClientService => {
+  const alias = opts.alias ?? EMAIL_LOGIN_SERVICE
+
+  let options: EmailAuthOptionsView | null = null
+  let screen: EmailLoginScreenComponent | null = opts.screen ?? null
+
+  const ctx = (): EmailLoginClientContext =>
+    service.assertCtx<ClientConfig, EmailLoginClientContext>(alias)
+
+  const service: EmailLoginClientService = createLazyService<EmailLoginClientService>(alias, {
+    protocols: () => protocols,
+
+    options: async request => {
+      if (request?.fresh !== true && options != null) {
+        return options
+      }
+      options = await ctx().entrypoint(protocols.options).call({})
+
+      return options
+    },
+
+    sendPin: async request => await ctx().entrypoint(protocols.pin).call({ body: request }),
+
+    signIn: async request => await ctx().entrypoint(protocols.signIn).call({ body: request }),
+
+    complete: async view => {
+      if (view.token == null || view.token === '') {
+        throw new EmailAuthError('answer')
+      }
+      const context = ctx()
+      await context.service<AuthService>(AUTH_SERVICE).authenticate({ token: view.token })
+
+      // Kept AFTER the token is adopted, so the ticket names the account it belongs to and a sign-in
+      // that failed keeps nothing. Any older ticket is dropped by the sign-in that does not bring one.
+      if (view.offer != null && view.offer !== '') {
+        emailStorageHelper.keepOffer(view.offer, signedInAccount(context))
+      } else {
+        emailStorageHelper.dropOffer()
+      }
+
+      // The supervisor and Google plugins land the same way: a full load of the landing, which
+      // inside a surrogate window is the dispatcher that hands the session back to the opener.
+      const landings = loginLandingOf(context)
+      const landing = await landings.landAfterLogin()
+      window.location.href = await landings.landingUrl(landing)
+    },
+
+    passwordStatus: async () => await ctx().entrypoint(protocols.password.status).call({}),
+
+    passwordPin: async request => await ctx().entrypoint(protocols.password.pin).call({ body: request }),
+
+    setPassword: async request => await ctx().entrypoint(protocols.password.set).call({ body: request }),
+
+    removePassword: async request => await ctx().entrypoint(protocols.password.remove).call({ body: request }),
+
+    declinePassword: async () => await ctx().entrypoint(protocols.password.decline).call({ body: {} }),
+
+    screen: () => screen,
+
+    registerScreen: next => { screen = next },
+  })
+
+  return service
+}
+
+/** Register the client service, unless the application already registered its own under the alias. */
+export const appendEmailLoginClient = (
+  context: EmailLoginClientContext, protocols: EmailAuthEntrypoints, opts: MakeEmailLoginClientOptions = {},
+): void => {
+  const alias = opts.alias ?? EMAIL_LOGIN_SERVICE
+  if (!context.hasService(alias)) {
+    context.registerService(makeEmailLoginClient(protocols, opts))
+  }
+}

package/src/state/types.ts

@@ -0,0 +1,72 @@
+import type { EmailAuthOptionsView } from '@owlmeans/auth-email'
+import type { EmailRefusal } from '../refusal/types.js'
+
+/** Which part of the form is showing. `done` = signed in, the browser is leaving. */
+export type EmailLoginStep = 'email' | 'pin' | 'password' | 'done'
+
+/** The call in flight: mailing a PIN, or signing in (PIN or password). */
+export type EmailLoginBusy = 'send' | 'sign-in'
+
+/** Why the PIN step is up: a code was asked for, or a password sign-in met an unknown device. */
+export type EmailLoginNotice = 'sent' | 'device'
+
+/** The whole e-mail sign-in form, as a plain value. */
+export interface EmailLoginState {
+  step: EmailLoginStep
+  email: string
+  pin: string
+  password: string
+  /** The password field shows what was typed. */
+  reveal: boolean
+  /** The signed challenge of the PIN mailed last; null until one is. */
+  challenge: string | null
+  notice: EmailLoginNotice | null
+  busy: EmailLoginBusy | null
+  refusal: EmailRefusal | null
+  /** What the deployment offers; null until `GET options` answered. */
+  options: EmailAuthOptionsView | null
+  /** The options read failed — the form still works, and the next send asks again. */
+  optionsFailed: boolean
+}
+
+/** Everything that changes the form. */
+export type EmailLoginAction =
+  | { type: 'options', options: EmailAuthOptionsView }
+  | { type: 'options-failed' }
+  | { type: 'email', value: string }
+  | { type: 'pin', value: string }
+  | { type: 'password', value: string }
+  | { type: 'reveal', value: boolean }
+  | { type: 'choose-password' }
+  | { type: 'choose-pin' }
+  | { type: 'change-email' }
+  | { type: 'start', busy: EmailLoginBusy }
+  | { type: 'sent', challenge: string }
+  | { type: 'device', challenge: string }
+  | { type: 'signed-in' }
+  | { type: 'refused', refusal: EmailRefusal }
+
+/**
+ * The e-mail sign-in form as pure transitions — what `useEmailLogin` runs through `useReducer`, and
+ * what a replacement screen or a test can drive without a DOM.
+ */
+export interface EmailLoginStateHelper {
+  /** The empty form on its e-mail step. */
+  initial: (email?: string) => EmailLoginState
+  /** The next form after `action`. Never mutates `state`. */
+  reduce: (state: EmailLoginState, action: EmailLoginAction) => EmailLoginState
+  /** A plausible address: one `@`, a dotted domain, no spaces, within the wire bound. */
+  validEmail: (email: string) => boolean
+  /** The address as it is sent: trimmed and lowercased. */
+  normalizeEmail: (email: string) => string
+  /** Digits in a PIN — the deployment's own when known. */
+  pinLength: (state: EmailLoginState) => number
+  /** Password sign-in is offered here. */
+  passwordOffered: (state: EmailLoginState) => boolean
+  /** What stops "send a PIN" right now (the address), or null when it may go. */
+  sendBlock: (state: EmailLoginState) => EmailRefusal | null
+  /** What stops "sign in with the PIN" right now, or null when it may go. */
+  verifyBlock: (state: EmailLoginState) => EmailRefusal | null
+  /** What stops a password sign-in right now, or null when it may go. */
+  signInBlock: (state: EmailLoginState) => EmailRefusal | null
+}

package/src/state.ts

@@ -0,0 +1,115 @@
+import { EMAIL_ADDRESS_MAX_LENGTH, EMAIL_PIN_LENGTH } from '@owlmeans/auth-email'
+import type { EmailRefusal } from './refusal/types.js'
+import type { EmailLoginAction, EmailLoginState, EmailLoginStateHelper } from './state/types.js'
+
+export const createEmailLoginStateHelper = (): EmailLoginStateHelper => {
+  const address = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+  const initial = (email: string = ''): EmailLoginState => ({
+    step: 'email', email, pin: '', password: '', reveal: false, challenge: null, notice: null,
+    busy: null, refusal: null, options: null, optionsFailed: false,
+  })
+
+  const normalizeEmail = (email: string): string => email.trim().toLowerCase()
+
+  const validEmail = (email: string): boolean => {
+    const value = normalizeEmail(email)
+
+    return value.length <= EMAIL_ADDRESS_MAX_LENGTH && address.test(value)
+  }
+
+  const pinLength = (state: EmailLoginState): number => state.options?.pinLength ?? EMAIL_PIN_LENGTH
+
+  const passwordOffered = (state: EmailLoginState): boolean => state.options?.password === true
+
+  const sendBlock = (state: EmailLoginState): EmailRefusal | null =>
+    validEmail(state.email) ? null : { kind: 'email' }
+
+  const verifyBlock = (state: EmailLoginState): EmailRefusal | null => {
+    if (state.challenge == null) {
+      // Nothing was mailed for this form yet — the person has to ask for a code first.
+      return { kind: 'code' }
+    }
+
+    return new RegExp(`^[0-9]{${pinLength(state)}}$`).test(state.pin) ? null : { kind: 'pin-format' }
+  }
+
+  const signInBlock = (state: EmailLoginState): EmailRefusal | null => {
+    if (!validEmail(state.email)) {
+      return { kind: 'email' }
+    }
+    if (!passwordOffered(state)) {
+      return { kind: 'password-disabled' }
+    }
+
+    return state.password === '' ? { kind: 'password-empty' } : null
+  }
+
+  const reduce = (state: EmailLoginState, action: EmailLoginAction): EmailLoginState => {
+    switch (action.type) {
+      case 'options':
+        return {
+          ...state, options: action.options, optionsFailed: false,
+          // The deployment turned passwords off under an open password step: back to the code.
+          ...(state.step === 'password' && action.options.password !== true
+            ? { step: 'email', password: '', reveal: false } : {}),
+        }
+      case 'options-failed':
+        return { ...state, optionsFailed: true }
+      case 'email':
+        return state.step === 'done' ? state : { ...state, email: action.value, refusal: null }
+      case 'pin':
+        return state.step === 'done' ? state : {
+          ...state, pin: action.value.replace(/\D/g, '').slice(0, pinLength(state)), refusal: null,
+        }
+      case 'password':
+        return state.step === 'done' ? state : { ...state, password: action.value, refusal: null }
+      case 'reveal':
+        return { ...state, reveal: action.value }
+      case 'choose-password':
+        return state.busy != null || !passwordOffered(state) || state.step === 'done' ? state : {
+          ...state, step: 'password', pin: '', notice: null, refusal: null,
+        }
+      case 'choose-pin':
+        return state.busy != null || state.step === 'done' ? state : {
+          ...state, step: 'email', password: '', reveal: false, refusal: null,
+        }
+      case 'change-email':
+        return state.busy != null || state.step === 'done' ? state : {
+          ...state, step: 'email', pin: '', password: '', reveal: false, challenge: null, notice: null, refusal: null,
+        }
+      case 'start':
+        return state.busy != null || state.step === 'done' ? state : { ...state, busy: action.busy, refusal: null }
+      case 'sent':
+        return { ...state, step: 'pin', challenge: action.challenge, notice: 'sent', pin: '', busy: null, refusal: null }
+      case 'device':
+        // A password sign-in on a device the account does not know: the password was NOT checked,
+        // a PIN was mailed instead, and the password is not kept around for later.
+        return {
+          ...state, step: 'pin', challenge: action.challenge, notice: 'device', pin: '', password: '',
+          reveal: false, busy: null, refusal: null,
+        }
+      case 'signed-in':
+        // Nothing secret stays in the form while the browser is leaving.
+        return { ...state, step: 'done', pin: '', password: '', reveal: false, busy: null, refusal: null }
+      case 'refused':
+        return {
+          ...state,
+          // Completing a sign-in failed after the answer: the person starts over from the address.
+          ...(state.step === 'done' ? { step: 'email', challenge: null, notice: null } : {}),
+          busy: null,
+          refusal: action.refusal,
+          ...(action.refusal.kind === 'code' ? { pin: '' } : {}),
+          ...(action.refusal.kind === 'credentials' ? { password: '' } : {}),
+        }
+      default:
+        return state
+    }
+  }
+
+  return {
+    initial, reduce, validEmail, normalizeEmail, pinLength, passwordOffered, sendBlock, verifyBlock, signInBlock,
+  }
+}
+
+export const emailLoginStateHelper = createEmailLoginStateHelper()

package/src/step.ts

@@ -0,0 +1,38 @@
+import type { LoginStep } from '@owlmeans/client-auth/login'
+import { EMAIL_OFFER_LOGIN_STEP, EMAIL_OFFER_STEP_PRIORITY } from './consts.js'
+import { emailStorageHelper } from './storage.js'
+import type { EmailStorageHelper } from './storage/types.js'
+import type { EmailLoginClientService } from './types.js'
+import { signedInAccount } from './utils/account.js'
+
+/**
+ * The post-sign-in "set a password" step.
+ *
+ * Pending only while BOTH hold: this tab keeps an offer ticket from a fresh PIN sign-in (unexpired,
+ * this account's), and the account's password status still says enabled, unset and not declined.
+ * A ticket the status no longer allows is forgotten on the spot. Optional: a status read that throws
+ * or hangs is "not pending" (the login host fails open), so a broken read never blocks a sign-in.
+ *
+ * Its priority sits below the marketing-consent step, so a Terms confirmation and the consent
+ * choices come first.
+ */
+export const emailOfferStep = (
+  client: Pick<EmailLoginClientService, 'passwordStatus'>, entrypointAlias: string,
+  storage: EmailStorageHelper = emailStorageHelper,
+): LoginStep => ({
+  alias: EMAIL_OFFER_LOGIN_STEP,
+  priority: EMAIL_OFFER_STEP_PRIORITY,
+  entrypoint: entrypointAlias,
+  pending: async ctx => {
+    if (storage.offer(signedInAccount(ctx)) == null) {
+      return false
+    }
+    const status = await client.passwordStatus()
+    if (status.enabled && !status.set && !status.declined) {
+      return true
+    }
+    storage.dropOffer()
+
+    return false
+  },
+})

package/src/storage/types.ts

@@ -0,0 +1,43 @@
+/** The part of a Web Storage this package uses. */
+export interface EmailStorageArea extends Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> {}
+
+export interface EmailStorageHelperOptions {
+  /** Where the device id lives. Default: `window.localStorage`, or nothing when it is unavailable. */
+  local?: () => EmailStorageArea | null
+  /** Where the offer ticket waits. Default: `window.sessionStorage`, or nothing when it is unavailable. */
+  session?: () => EmailStorageArea | null
+  /** `count` random bytes. Default: `crypto.getRandomValues`. */
+  random?: (count: number) => Uint8Array
+  /** The clock, in milliseconds. Default: `Date.now`. */
+  now?: () => number
+}
+
+/** The offer ticket as it is kept — with the account it was issued to and when it stops counting. */
+export interface StoredEmailOffer {
+  ticket: string
+  owner?: string
+  expiresAt: number
+}
+
+/**
+ * What a browser keeps for e-mail sign-in: its device id, and a fresh PIN sign-in's offer ticket.
+ *
+ * Every storage access tolerates a browser that refuses site data (private modes, blocked
+ * storage): the device id then lives for the page alone, and no offer is shown.
+ */
+export interface EmailStorageHelper {
+  /**
+   * This browser's device id — 16 random bytes, base64url (22 characters). Created on first use and
+   * kept in `localStorage`; without storage, one id for as long as this page lives.
+   */
+  deviceId: () => string
+  /**
+   * The waiting offer ticket, or null — also when it has expired, or was issued to another account
+   * than `owner` (when both are known).
+   */
+  offer: (owner?: string) => string | null
+  /** Keep a PIN sign-in's offer ticket for the offer step, until `EMAIL_OFFER_TTL_SECONDS` pass. */
+  keepOffer: (ticket: string, owner?: string) => void
+  /** Forget the offer ticket — it was used, declined, or cannot be used any more. */
+  dropOffer: () => void
+}

package/src/storage.ts

@@ -0,0 +1,113 @@
+import { EMAIL_DEVICE_ID_PATTERN, EMAIL_OFFER_TTL_SECONDS } from '@owlmeans/auth-email'
+import { EMAIL_DEVICE_ID_BYTES, EMAIL_DEVICE_STORAGE, EMAIL_OFFER_STORAGE } from './consts.js'
+import type {
+  EmailStorageArea, EmailStorageHelper, EmailStorageHelperOptions, StoredEmailOffer,
+} from './storage/types.js'
+
+/** A storage area of the page, or null where there is no page or the browser refuses it. */
+const areaOf = (name: 'localStorage' | 'sessionStorage') => (): EmailStorageArea | null => {
+  try {
+    return typeof window !== 'undefined' ? window[name] ?? null : null
+  } catch {
+    return null
+  }
+}
+
+export const createEmailStorageHelper = (opts: EmailStorageHelperOptions = {}): EmailStorageHelper => {
+  const local = opts.local ?? areaOf('localStorage')
+  const session = opts.session ?? areaOf('sessionStorage')
+  const random = opts.random ?? ((count: number) => crypto.getRandomValues(new Uint8Array(count)))
+  const now = opts.now ?? (() => Date.now())
+  const valid = new RegExp(EMAIL_DEVICE_ID_PATTERN)
+
+  /** The id of this page when the browser keeps nothing — still one id, not one per request. */
+  let ephemeral: string | null = null
+
+  const base64url = (bytes: Uint8Array): string => {
+    let binary = ''
+    for (const byte of bytes) {
+      binary += String.fromCharCode(byte)
+    }
+
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+  }
+
+  const read = (area: EmailStorageArea | null, key: string): string | null => {
+    try {
+      return area?.getItem(key) ?? null
+    } catch {
+      return null
+    }
+  }
+
+  const write = (area: EmailStorageArea | null, key: string, value: string | null): boolean => {
+    if (area == null) {
+      return false
+    }
+    try {
+      if (value == null) {
+        area.removeItem(key)
+      } else {
+        area.setItem(key, value)
+      }
+
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  const deviceId = (): string => {
+    const area = local()
+    const stored = read(area, EMAIL_DEVICE_STORAGE)
+    if (stored != null && valid.test(stored)) {
+      return stored
+    }
+    if (ephemeral != null) {
+      return ephemeral
+    }
+    const created = base64url(random(EMAIL_DEVICE_ID_BYTES))
+    if (!write(area, EMAIL_DEVICE_STORAGE, created)) {
+      ephemeral = created
+    }
+
+    return created
+  }
+
+  const offer = (owner?: string): string | null => {
+    const raw = read(session(), EMAIL_OFFER_STORAGE)
+    if (raw == null) {
+      return null
+    }
+    let stored: Partial<StoredEmailOffer> | null = null
+    try {
+      stored = JSON.parse(raw) as Partial<StoredEmailOffer>
+    } catch {
+      return null
+    }
+    if (typeof stored?.ticket !== 'string' || stored.ticket === ''
+      || typeof stored.expiresAt !== 'number' || stored.expiresAt <= now()) {
+      return null
+    }
+    if (owner != null && stored.owner != null && stored.owner !== owner) {
+      return null
+    }
+
+    return stored.ticket
+  }
+
+  const keepOffer = (ticket: string, owner?: string): void => {
+    const stored: StoredEmailOffer = {
+      ticket, ...(owner != null ? { owner } : {}), expiresAt: now() + EMAIL_OFFER_TTL_SECONDS * 1000,
+    }
+    write(session(), EMAIL_OFFER_STORAGE, JSON.stringify(stored))
+  }
+
+  const dropOffer = (): void => {
+    write(session(), EMAIL_OFFER_STORAGE, null)
+  }
+
+  return { deviceId, offer, keepOffer, dropOffer }
+}
+
+export const emailStorageHelper = createEmailStorageHelper()

package/src/types.ts

@@ -0,0 +1,111 @@
+import type { ComponentType } from 'react'
+import type { LazyService } from '@owlmeans/context'
+import type { ClientConfig, ClientContext } from '@owlmeans/client-context'
+import type { AuthMethodMeta } from '@owlmeans/client-auth/manager/plugins'
+import type { LoginScreenProps } from '@owlmeans/client-auth/login'
+import type {
+  EmailAuthEntrypoints, EmailAuthOptionsView, EmailChallengeView, EmailPasswordPinRequest,
+  EmailPasswordRemoveRequest, EmailPasswordSetRequest, EmailPasswordStatusView, EmailPinRequest,
+  EmailSignInRequest, EmailSignInView,
+} from '@owlmeans/auth-email'
+
+/**
+ * `(key, defaultValue) => string` — this package's own translator, or an application's.
+ *
+ * Keys are this package's (`login.title`, `error.code`, …, resource `auth-email`); the default is
+ * the English text. Placeholders such as `{{email}}` are filled by the component, so a translator
+ * returns the sentence as it is.
+ */
+export interface Translate { (key: string, defaultValue: string): string }
+
+/**
+ * How an application dresses the e-mail sign-in card — the same props the chooser card
+ * (`@owlmeans/web-panel`'s `LoginScreen`) takes for the same purpose.
+ */
+export interface EmailLoginScreenSetup extends Pick<
+  LoginScreenProps,
+  'Logo' | 'title' | 'subtitle' | 'footer' | 'className' | 'containerClassName' | 'style' | 'locale' | 'translate'
+> {}
+
+export interface EmailLoginScreenProps extends EmailLoginScreenSetup {}
+
+export type EmailLoginScreenComponent = ComponentType<EmailLoginScreenProps>
+
+export interface EmailLoginAppendOptions {
+  /**
+   * From `makeEmailAuthProtocols(...)` — the tree the application also binds with `bindAll` (the
+   * API routes) and `emailAuthEntrypoints` (the offer screen).
+   */
+  protocols: EmailAuthEntrypoints
+  /** Logo, copy and classes of the e-mail card; merged under the props a host passes itself. */
+  screen?: EmailLoginScreenSetup
+  /**
+   * How the method presents itself on the chooser, merged over `EMAIL_LOGIN_METHOD_META`.
+   * `available` is always this package's own (the client service is registered).
+   */
+  method?: Partial<AuthMethodMeta>
+  /** Register the post-sign-in "set a password" step. Default `true`. */
+  offer?: boolean
+}
+
+export type EmailLoginClientContext = ClientContext<ClientConfig>
+
+/**
+ * The browser side of e-mail sign-in, registered as `EMAIL_LOGIN_SERVICE` by `appendEmailLogin`.
+ *
+ * A thin transport over the protocol tree: every call rejects with the error its route answered,
+ * and the caller phrases it (`emailRefusalHelper`). Nothing here swallows a failure.
+ */
+export interface EmailLoginClientService extends LazyService {
+  /** The protocol tree the service calls. */
+  protocols: () => EmailAuthEntrypoints
+  /** `GET options`, cached after the first success; `fresh` asks again. */
+  options: (opts?: { fresh?: boolean }) => Promise<EmailAuthOptionsView>
+  /** `POST pin` — mail a sign-in PIN. */
+  sendPin: (request: EmailPinRequest) => Promise<EmailChallengeView>
+  /** `POST sign-in` — PIN mode or password mode. */
+  signIn: (request: EmailSignInRequest) => Promise<EmailSignInView>
+  /**
+   * Finish a signed-in answer the way every self-contained plugin does: adopt the token through the
+   * client auth service, keep the offer ticket (when one came) for the offer step, then land with
+   * `loginLandingOf(ctx).landAfterLogin()` — a pending step, a parked target, else home; inside a
+   * surrogate window the dispatcher, which hands the session to the opener.
+   *
+   * @throws when the answer carries no token, or the token is refused.
+   */
+  complete: (view: EmailSignInView) => Promise<void>
+  /** `GET password` — the signed-in account's password state. */
+  passwordStatus: () => Promise<EmailPasswordStatusView>
+  /** `POST password/pin` — mail a confirmation PIN to the account's own address. */
+  passwordPin: (request: EmailPasswordPinRequest) => Promise<EmailChallengeView>
+  /** `POST password/set`. */
+  setPassword: (request: EmailPasswordSetRequest) => Promise<EmailPasswordStatusView>
+  /** `POST password/remove`. */
+  removePassword: (request: EmailPasswordRemoveRequest) => Promise<EmailPasswordStatusView>
+  /** `POST password/decline` — "Not now" on the offer. */
+  declinePassword: () => Promise<EmailPasswordStatusView>
+  /** The screen the e-mail route renders; null = the package's own. */
+  screen: () => EmailLoginScreenComponent | null
+  /** Replace the screen the e-mail route renders (`registerEmailLoginScreen`). */
+  registerScreen: (screen: EmailLoginScreenComponent) => void
+}
+
+export interface MakeEmailLoginClientOptions {
+  alias?: string
+  /** The screen the e-mail route renders until another is registered. */
+  screen?: EmailLoginScreenComponent
+}
+
+/**
+ * The entrypoint aliases `usePassword` addresses.
+ *
+ * By default those of the tree given to `appendEmailLogin`, else the `EMAIL_AUTH_PASSWORD_*` aliases
+ * `makeEmailAuthProtocols` declares — an application that mounted the password routes under its own
+ * aliases (a facade in front of them, say) passes its own here.
+ */
+export interface EmailPasswordAliases {
+  status: string
+  pin: string
+  set: string
+  remove: string
+}

package/src/utils/account.ts

@@ -0,0 +1,12 @@
+import type { AuthService } from '@owlmeans/auth-common'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { DEFAULT_ALIAS as AUTH_SERVICE } from '@owlmeans/client-auth'
+
+/** The signed-in account's id, when the client auth service can say — the owner of an offer ticket. */
+export const signedInAccount = <C extends BasicConfig>(ctx: BasicContext<C>): string | undefined => {
+  try {
+    return ctx.service<AuthService>(AUTH_SERVICE).user().userId
+  } catch {
+    return undefined
+  }
+}

package/src/utils/locale.ts

@@ -0,0 +1,11 @@
+import { EMAIL_LOCALE_MAX_LENGTH } from '@owlmeans/auth-email'
+
+/**
+ * The language a request names for its mail: the base language of the interface's (`de-AT` → `de`),
+ * or nothing when there is none to name — the server then writes in English.
+ */
+export const wireLocale = (locale?: string): string | undefined => {
+  const base = locale?.trim().split(/[-_]/)[0]?.toLowerCase()
+
+  return base != null && base !== '' && base.length <= EMAIL_LOCALE_MAX_LENGTH ? base : undefined
+}

package/src/utils/text/types.ts

@@ -0,0 +1,24 @@
+/** One run of a sentence: plain text, or a link. */
+export interface TextPart {
+  text: string
+  href?: string
+  /** The placeholder this part replaced, for a link. */
+  key?: string
+}
+
+export interface TextLink {
+  text: string
+  href: string
+}
+
+/**
+ * Placeholders in an already-translated sentence. Translations keep `{{name}}` untouched when no
+ * value is passed (i18next's `skipOnVariables`), and an app's own `translate` has no values at
+ * all — so every package string is filled here, the same way whichever translator produced it.
+ */
+export interface TextUtils {
+  /** Replace every `{{name}}` that `values` names; others stay as they are. */
+  fill: (template: string, values: Record<string, string | number>) => string
+  /** Split a sentence around the `{{name}}` placeholders `links` names, turning each into a link. */
+  parts: (template: string, links: Record<string, TextLink>) => TextPart[]
+}

package/src/utils/text.ts

@@ -0,0 +1,34 @@
+import type { TextLink, TextPart, TextUtils } from './text/types.js'
+
+export const createTextUtils = (): TextUtils => {
+  const placeholder = /\{\{\s*([\w-]+)\s*\}\}/g
+
+  const fill = (template: string, values: Record<string, string | number>): string =>
+    template.replace(placeholder, (match, name: string) =>
+      Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : match)
+
+  const parts = (template: string, links: Record<string, TextLink>): TextPart[] => {
+    const result: TextPart[] = []
+    let last = 0
+    for (const match of template.matchAll(placeholder)) {
+      const link = links[match[1]]
+      if (link == null) {
+        continue
+      }
+      if (match.index > last) {
+        result.push({ text: template.slice(last, match.index) })
+      }
+      result.push({ text: link.text, href: link.href, key: match[1] })
+      last = match.index + match[0].length
+    }
+    if (last < template.length) {
+      result.push({ text: template.slice(last) })
+    }
+
+    return result
+  }
+
+  return { fill, parts }
+}
+
+export const textUtils = createTextUtils()