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

package/src/utils.ts

@@ -0,0 +1,9 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * The class-name merger the components here are written against, exported so a replacement screen
+ * built on `useEmailLogin()` need not declare its own copy. Not a re-export of the private
+ * `src/@/lib/utils` — that tree is this package's own and is never exposed.
+ */
+export const cn = (...inputs: ClassValue[]): string => twMerge(clsx(inputs))

package/tests/helpers.ts

@@ -0,0 +1,22 @@
+import type { EmailStorageArea } from '../src/storage/types.js'
+
+/** A Web Storage area in memory; `failing` makes every call throw, as a browser refusing site data does. */
+export const memoryArea = (failing = false): EmailStorageArea & { data: Map<string, string> } => {
+  const data = new Map<string, string>()
+  const guard = (): void => {
+    if (failing) {
+      throw new Error('SecurityError: storage is disabled')
+    }
+  }
+
+  return {
+    data,
+    getItem: key => { guard(); return data.get(key) ?? null },
+    setItem: (key, value) => { guard(); data.set(key, value) },
+    removeItem: key => { guard(); data.delete(key) },
+  }
+}
+
+/** Deterministic "random" bytes: 0, 1, 2, … from `start`. */
+export const counting = (start = 0) => (count: number): Uint8Array =>
+  Uint8Array.from({ length: count }, (_, index) => (start + index) % 256)

package/tests/i18n.spec.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test'
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import en from '../src/i18n/en.json' with { type: 'json' }
+import pl from '../src/i18n/pl.json' with { type: 'json' }
+import ru from '../src/i18n/ru.json' with { type: 'json' }
+import be from '../src/i18n/be.json' with { type: 'json' }
+import uk from '../src/i18n/uk.json' with { type: 'json' }
+import es from '../src/i18n/es.json' with { type: 'json' }
+import de from '../src/i18n/de.json' with { type: 'json' }
+import fr from '../src/i18n/fr.json' with { type: 'json' }
+import authEn from '../src/i18n/auth/en.json' with { type: 'json' }
+import authPl from '../src/i18n/auth/pl.json' with { type: 'json' }
+import authRu from '../src/i18n/auth/ru.json' with { type: 'json' }
+import authBe from '../src/i18n/auth/be.json' with { type: 'json' }
+import authUk from '../src/i18n/auth/uk.json' with { type: 'json' }
+import authEs from '../src/i18n/auth/es.json' with { type: 'json' }
+import authDe from '../src/i18n/auth/de.json' with { type: 'json' }
+import authFr from '../src/i18n/auth/fr.json' with { type: 'json' }
+import { EMAIL_AUTH_LOCALES } from '@owlmeans/auth-email'
+
+const LANGUAGES: Record<string, unknown> = { en, pl, ru, be, uk, es, de, fr }
+const AUTH: Record<string, { login: { method: { email: string } } }> = {
+  en: authEn, pl: authPl, ru: authRu, be: authBe, uk: authUk, es: authEs, de: authDe, fr: authFr,
+}
+
+/** Every leaf key path in a nested translation object, e.g. `login.title`. */
+const leaves = (value: unknown, prefix = ''): string[] => typeof value !== 'object' || value == null
+  ? [prefix]
+  : Object.entries(value as Record<string, unknown>)
+    .flatMap(([key, child]) => leaves(child, prefix === '' ? key : `${prefix}.${key}`))
+
+const valueOf = (resource: unknown, key: string): unknown =>
+  key.split('.').reduce<unknown>((node, part) => (node as Record<string, unknown> | undefined)?.[part], resource)
+
+const placeholders = (text: string): string[] => [...text.matchAll(/\{\{\s*([\w-]+)\s*\}\}/g)].map(m => m[1]).sort()
+
+const sourceFiles = (dir: string): string[] => readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+  const path = join(dir, entry.name)
+
+  return entry.isDirectory() ? sourceFiles(path) : /\.tsx?$/.test(entry.name) ? [path] : []
+})
+
+/** Every `t('key', 'English default')` in the sources, with its default. */
+const used = (): Map<string, string> => {
+  const result = new Map<string, string>()
+  const call = /\bt\(\s*'([^']+)'\s*,\s*(?:'((?:[^'\\]|\\.)*)'|"((?:[^"\\]|\\.)*)")/g
+  for (const file of sourceFiles(join(import.meta.dir, '../src'))) {
+    for (const match of readFileSync(file, 'utf8').matchAll(call)) {
+      result.set(match[1], (match[2] ?? match[3]).replace(/\\'/g, "'").replace(/\\"/g, '"'))
+    }
+  }
+
+  return result
+}
+
+describe('@owlmeans/web-auth-email — translations', () => {
+  const english = leaves(en).sort()
+
+  test('ships exactly the eight sign-in languages', () => {
+    expect(Object.keys(LANGUAGES).sort()).toEqual([...EMAIL_AUTH_LOCALES].sort())
+    expect(Object.keys(AUTH).sort()).toEqual([...EMAIL_AUTH_LOCALES].sort())
+  })
+
+  for (const [lng, resource] of Object.entries(LANGUAGES)) {
+    test(`${lng}: the same keys as English, none empty, the same placeholders`, () => {
+      expect(leaves(resource).sort()).toEqual(english)
+      for (const key of english) {
+        const value = valueOf(resource, key)
+        expect(typeof value === 'string' && value.trim() !== '').toBe(true)
+        expect(placeholders(value as string)).toEqual(placeholders(valueOf(en, key) as string))
+      }
+    })
+  }
+
+  test('every key a component asks for exists, and its English default is the bundle text', () => {
+    const keys = used()
+    // An empty scan would make the rest pass vacuously.
+    expect(keys.size).toBeGreaterThanOrEqual(60)
+    for (const [key, defaultValue] of keys) {
+      expect(valueOf(en, key)).toBe(defaultValue)
+    }
+    // …and nothing in the bundle is dead.
+    expect([...keys.keys()].sort()).toEqual(english)
+  })
+
+  test('login.method.email reaches the auth resource in every language', () => {
+    for (const resource of Object.values(AUTH)) {
+      expect(leaves(resource)).toEqual(['login.method.email'])
+      expect(resource.login.method.email.trim()).not.toBe('')
+    }
+    expect(authEn.login.method.email).toBe('Continue with email')
+  })
+})

package/tests/package-boundary.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test'
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const source = join(import.meta.dir, '../src')
+
+const sourceFiles = (dir: string): string[] => readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+  const path = join(dir, entry.name)
+
+  return entry.isDirectory() ? sourceFiles(path) : [path]
+})
+
+describe('@owlmeans/web-auth-email — package boundary', () => {
+  const files = sourceFiles(source).filter(file => /\.tsx?$/.test(file))
+
+  test('does not use consumer-project UI aliases in package source', () => {
+    for (const file of files) {
+      expect(readFileSync(file, 'utf8')).not.toMatch(/from\s+['"]@\//)
+    }
+  })
+
+  test('never depends on a panel package and never logs through console', () => {
+    for (const file of files) {
+      const text = readFileSync(file, 'utf8')
+      expect(text).not.toMatch(/from\s+['"]@owlmeans\/(web|mui|client)-panel/)
+      expect(text).not.toMatch(/\bconsole\./)
+    }
+  })
+
+  test('never renders a natively disabled control', () => {
+    for (const file of files.filter(file => file.endsWith('.tsx') && !file.includes('/@/'))) {
+      expect(readFileSync(file, 'utf8')).not.toMatch(/\sdisabled=\{/)
+    }
+  })
+})

package/tests/password.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test'
+import { EMAIL_PASSWORD_MAX_LENGTH, EMAIL_PASSWORD_MIN_LENGTH, EmailPasswordPurpose } from '@owlmeans/auth-email'
+import { passwordPanelHelper as helper } from '../src/password.js'
+
+describe('passwordPanelHelper — state and actions', () => {
+  test('loading, unreadable, off, unset and set', () => {
+    expect(helper.stateOf(null, true)).toBe('loading')
+    expect(helper.stateOf(null, false)).toBe('unreadable')
+    expect(helper.stateOf({ enabled: false, set: false, declined: false }, false)).toBe('off')
+    expect(helper.stateOf({ enabled: true, set: false, declined: true }, false)).toBe('unset')
+    expect(helper.stateOf({ enabled: true, set: true, declined: false }, true)).toBe('set')
+  })
+
+  test('set without a password; change and remove with one; nothing when off or unknown', () => {
+    expect(helper.actionsOf({ enabled: true, set: false, declined: false })).toEqual(['set'])
+    expect(helper.actionsOf({ enabled: true, set: true, declined: false })).toEqual(['change', 'remove'])
+    expect(helper.actionsOf({ enabled: false, set: true, declined: false })).toEqual([])
+    expect(helper.actionsOf(null)).toEqual([])
+  })
+
+  test('each action asks for its own confirmation purpose', () => {
+    expect(helper.purposeOf('set')).toBe(EmailPasswordPurpose.Set)
+    expect(helper.purposeOf('change')).toBe(EmailPasswordPurpose.Change)
+    expect(helper.purposeOf('remove')).toBe(EmailPasswordPurpose.Remove)
+    expect(helper.needsPassword('remove')).toBe(false)
+    expect(helper.needsPassword('change')).toBe(true)
+  })
+})
+
+describe('passwordPanelHelper — what stops a confirmation', () => {
+  const good = 'a'.repeat(EMAIL_PASSWORD_MIN_LENGTH)
+
+  test('the PIN first, then the password: empty, out of bounds, not repeated', () => {
+    expect(helper.confirmBlock('set', { pin: '12345', password: good, repeat: good })).toEqual({ kind: 'pin-format' })
+    expect(helper.confirmBlock('set', { pin: '123456', password: '', repeat: '' })).toEqual({ kind: 'password-empty' })
+    expect(helper.confirmBlock('set', { pin: '123456', password: 'short', repeat: 'short' })).toEqual({ kind: 'weak' })
+    const long = 'a'.repeat(EMAIL_PASSWORD_MAX_LENGTH + 1)
+    expect(helper.confirmBlock('change', { pin: '123456', password: long, repeat: long })).toEqual({ kind: 'weak' })
+    expect(helper.confirmBlock('change', { pin: '123456', password: good, repeat: `${good}!` })).toEqual({ kind: 'mismatch' })
+    expect(helper.confirmBlock('change', { pin: '123456', password: good, repeat: good })).toBeNull()
+  })
+
+  test('remove needs the PIN alone', () => {
+    expect(helper.confirmBlock('remove', { pin: '123456', password: '', repeat: '' })).toBeNull()
+    expect(helper.confirmBlock('remove', { pin: 'abcdef', password: '', repeat: '' })).toEqual({ kind: 'pin-format' })
+  })
+
+  test('length counts NFKC, as the server does', () => {
+    // Eight full-width letters NFKC-fold to eight ASCII ones — still eight.
+    const wide = 'ＡＢＣＤＥＦＧＨ'
+    expect(helper.passwordBlock(wide, wide)).toBeNull()
+    // "ff" (one ligature) folds to "ff" (two): seven ligatures read as fourteen characters.
+    const ligatures = 'ff'.repeat(7)
+    expect(helper.passwordBlock(ligatures, ligatures)).toBeNull()
+  })
+})

package/tests/refusal.spec.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'bun:test'
+import { AuthenFailed, AuthUnavailable } from '@owlmeans/auth'
+import { ApiClientError, ApiStatusError, ServerAuthError } from '@owlmeans/api'
+import { ResilientError } from '@owlmeans/error'
+import { EmailOfferExpired, EmailPasswordDisabled, EmailPasswordWeak } from '@owlmeans/auth-email'
+import { CaptchaLoadError } from '@owlmeans/web-captcha'
+import { emailRefusalHelper as helper } from '../src/refusal.js'
+import type { Translate } from '../src/types.js'
+
+const english: Translate = (_key, defaultValue) => defaultValue
+
+/** What the API client rejects with for a production answer: the status alone. */
+const status = (code: number) => Object.assign(code === 401 ? new ServerAuthError() : code === 403 ? new ApiClientError('forbidden') : new ApiStatusError(code), {
+  responseStatus: code,
+})
+
+/** What it rejects with for a development answer: the typed error, rebuilt from its wire form. */
+const wire = (error: Error) => ResilientError.ensure(ResilientError.marshal(error).message, true)
+
+describe('emailRefusalHelper — typed refusals (development bodies)', () => {
+  test('wrong password, wrong code, captcha and its outage', () => {
+    expect(helper.refusalOf(wire(new AuthenFailed('email:password')), 'password').kind).toBe('credentials')
+    expect(helper.refusalOf(wire(new AuthenFailed('otp:code')), 'pin').kind).toBe('code')
+    expect(helper.refusalOf(wire(new AuthenFailed('recaptcha:score')), 'send').kind).toBe('captcha')
+    expect(helper.refusalOf(wire(new AuthUnavailable('recaptcha:config')), 'send').kind).toBe('captcha-unavailable')
+    expect(helper.refusalOf(new CaptchaLoadError('timeout'), 'send').kind).toBe('captcha-unavailable')
+  })
+
+  test('the e-mail family: weak, expired offer, passwords off', () => {
+    expect(helper.refusalOf(wire(new EmailPasswordWeak()), 'set').kind).toBe('weak')
+    expect(helper.refusalOf(wire(new EmailOfferExpired()), 'offer').kind).toBe('offer-expired')
+    expect(helper.refusalOf(wire(new EmailPasswordDisabled()), 'password').kind).toBe('password-disabled')
+  })
+
+  test('a throttle names its wait only when one is known', () => {
+    const throttled = Object.assign(new ResilientError('OtpErrorThrottled', 'otp:throttled'), { retryAfter: 45 })
+    expect(helper.refusalOf(throttled, 'send')).toEqual({ kind: 'throttled', retryAfter: 45 })
+    // Rebuilt from the wire the number is lost (1) — no time is claimed then.
+    expect(helper.refusalOf(Object.assign(status(429), { retryAfter: 1 }), 'send')).toEqual({ kind: 'throttled' })
+  })
+})
+
+describe('emailRefusalHelper — status-only refusals (production bodies)', () => {
+  test('a 401 is a wrong code after a PIN and wrong credentials after a password', () => {
+    expect(helper.refusalOf(status(401), 'pin').kind).toBe('code')
+    expect(helper.refusalOf(status(401), 'password').kind).toBe('credentials')
+    expect(helper.refusalOf(status(401), 'send').kind).toBe('failed')
+  })
+
+  test('a 403 is the captcha on a guest route and the confirmation PIN on a signed-in one', () => {
+    expect(helper.refusalOf(status(403), 'send').kind).toBe('captcha')
+    expect(helper.refusalOf(status(403), 'password').kind).toBe('captcha')
+    expect(helper.refusalOf(status(403), 'confirm').kind).toBe('code')
+    expect(helper.refusalOf(status(403), 'set').kind).toBe('code')
+    expect(helper.refusalOf(status(403), 'remove').kind).toBe('code')
+  })
+
+  test('the server\'s own refusal classes, unknown here, still read by their message', () => {
+    const credential = new ResilientError('EmailCredentialRefused', 'auth:manager:authen:email:password')
+    const confirmation = new ResilientError('EmailVerificationRefused', 'auth:manager:authen:email:confirm:purpose')
+    expect(helper.refusalOf(Object.assign(credential, { responseStatus: 401 }), 'password').kind).toBe('credentials')
+    expect(helper.refusalOf(Object.assign(confirmation, { responseStatus: 403 }), 'remove').kind).toBe('code')
+  })
+
+  test('429, 422, 409, 503, 404, 400 and anything else', () => {
+    expect(helper.refusalOf(status(429), 'pin').kind).toBe('throttled')
+    expect(helper.refusalOf(status(422), 'set').kind).toBe('weak')
+    expect(helper.refusalOf(status(409), 'offer').kind).toBe('offer-expired')
+    expect(helper.refusalOf(status(503), 'send').kind).toBe('unavailable')
+    expect(helper.refusalOf(status(404), 'password').kind).toBe('password-disabled')
+    expect(helper.refusalOf(status(400), 'send').kind).toBe('email')
+    expect(helper.refusalOf(status(500), 'pin').kind).toBe('failed')
+    expect(helper.refusalOf(new Error('network'), 'pin').kind).toBe('failed')
+  })
+})
+
+describe('emailRefusalHelper — messages', () => {
+  test('a known wait is phrased by the language itself', () => {
+    expect(helper.messageOf({ kind: 'throttled', retryAfter: 45 }, english, 'en'))
+      .toBe('Too many attempts. Please try again in 45 seconds.')
+    expect(helper.messageOf({ kind: 'throttled', retryAfter: 600 }, english, 'en'))
+      .toBe('Too many attempts. Please try again in 10 minutes.')
+    expect(helper.messageOf({ kind: 'throttled' }, english)).toBe('Too many attempts. Please wait a little and try again.')
+  })
+
+  test('the policy and the code length fill their placeholders, whatever the translator', () => {
+    const raw: Translate = key => key === 'error.weak' ? 'Od {{min}} do {{max}}' : key
+    expect(helper.messageOf({ kind: 'weak' }, raw)).toBe('Od 8 do 128')
+    expect(helper.messageOf({ kind: 'pin-format' }, english)).toBe('Enter the code from the email: 6 digits.')
+  })
+})

package/tests/state.spec.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from 'bun:test'
+import type { EmailAuthOptionsView } from '@owlmeans/auth-email'
+import { emailLoginStateHelper as helper } from '../src/state.js'
+import type { EmailLoginAction, EmailLoginState } from '../src/state/types.js'
+
+const OPTIONS: EmailAuthOptionsView = { password: true, captcha: null, pinLength: 6 }
+
+const run = (...actions: EmailLoginAction[]): EmailLoginState =>
+  actions.reduce(helper.reduce, helper.initial())
+
+describe('emailLoginStateHelper — the PIN path', () => {
+  test('address → send → PIN step with the challenge → signed in', () => {
+    let state = run({ type: 'options', options: OPTIONS }, { type: 'email', value: ' Person@Example.COM ' })
+    expect(helper.sendBlock(state)).toBeNull()
+    expect(helper.normalizeEmail(state.email)).toBe('person@example.com')
+
+    state = helper.reduce(state, { type: 'start', busy: 'send' })
+    expect(state.busy).toBe('send')
+    state = helper.reduce(state, { type: 'sent', challenge: 'challenge-1' })
+    expect(state).toMatchObject({ step: 'pin', challenge: 'challenge-1', notice: 'sent', busy: null })
+
+    state = helper.reduce(state, { type: 'pin', value: '12 34-56 78' })
+    expect(state.pin).toBe('123456')
+    expect(helper.verifyBlock(state)).toBeNull()
+
+    state = helper.reduce(helper.reduce(state, { type: 'start', busy: 'sign-in' }), { type: 'signed-in' })
+    expect(state).toMatchObject({ step: 'done', pin: '', password: '', busy: null })
+  })
+
+  test('nothing is sent for an invalid address or an incomplete code', () => {
+    expect(helper.sendBlock(run({ type: 'email', value: 'no-at-sign' }))).toEqual({ kind: 'email' })
+    expect(helper.sendBlock(run({ type: 'email', value: `${'a'.repeat(250)}@example.com` }))).toEqual({ kind: 'email' })
+
+    const state = run({ type: 'email', value: 'a@b.co' }, { type: 'sent', challenge: 'c' }, { type: 'pin', value: '123' })
+    expect(helper.verifyBlock(state)).toEqual({ kind: 'pin-format' })
+  })
+
+  test('a wrong code clears the PIN and keeps the challenge; "Change email" forgets both', () => {
+    let state = run({ type: 'email', value: 'a@b.co' }, { type: 'sent', challenge: 'c' }, { type: 'pin', value: '111111' })
+    state = helper.reduce(state, { type: 'refused', refusal: { kind: 'code' } })
+    expect(state).toMatchObject({ step: 'pin', pin: '', challenge: 'c', refusal: { kind: 'code' } })
+
+    state = helper.reduce(state, { type: 'pin', value: '2' })
+    expect(state.refusal).toBeNull()
+
+    state = helper.reduce(state, { type: 'change-email' })
+    expect(state).toMatchObject({ step: 'email', pin: '', challenge: null, notice: null })
+  })
+
+  test('a second action while one is in flight changes nothing', () => {
+    const busy = run({ type: 'options', options: OPTIONS }, { type: 'email', value: 'a@b.co' }, { type: 'start', busy: 'send' })
+
+    expect(helper.reduce(busy, { type: 'start', busy: 'sign-in' })).toBe(busy)
+    expect(helper.reduce(busy, { type: 'choose-password' })).toBe(busy)
+    expect(helper.reduce(busy, { type: 'change-email' })).toBe(busy)
+  })
+})
+
+describe('emailLoginStateHelper — the password path', () => {
+  test('"Use it" exists only where the deployment offers passwords', () => {
+    const off = run({ type: 'options', options: { ...OPTIONS, password: false } }, { type: 'choose-password' })
+    expect(off.step).toBe('email')
+    expect(helper.passwordOffered(off)).toBe(false)
+
+    const on = run({ type: 'options', options: OPTIONS }, { type: 'choose-password' })
+    expect(on.step).toBe('password')
+    expect(helper.signInBlock(on)).toEqual({ kind: 'email' })
+    expect(helper.signInBlock(helper.reduce(helper.reduce(on, { type: 'email', value: 'a@b.co' }),
+      { type: 'password', value: '' }))).toEqual({ kind: 'password-empty' })
+  })
+
+  test('an unknown device turns into the PIN step, with the notice, and drops the password', () => {
+    const state = run(
+      { type: 'options', options: OPTIONS }, { type: 'choose-password' }, { type: 'email', value: 'a@b.co' },
+      { type: 'password', value: 'secret-password' }, { type: 'reveal', value: true },
+      { type: 'start', busy: 'sign-in' }, { type: 'device', challenge: 'device-challenge' },
+    )
+
+    expect(state).toMatchObject({
+      step: 'pin', notice: 'device', challenge: 'device-challenge', password: '', reveal: false, busy: null,
+    })
+  })
+
+  test('wrong credentials clear the password and keep the step; the options turning passwords off close it', () => {
+    let state = run({ type: 'options', options: OPTIONS }, { type: 'choose-password' }, { type: 'email', value: 'a@b.co' },
+      { type: 'password', value: 'wrong' }, { type: 'refused', refusal: { kind: 'credentials' } })
+    expect(state).toMatchObject({ step: 'password', password: '', refusal: { kind: 'credentials' } })
+
+    state = helper.reduce(state, { type: 'options', options: { ...OPTIONS, password: false } })
+    expect(state.step).toBe('email')
+  })
+
+  test('a failure after "signed in" sends the person back to the address', () => {
+    const state = run({ type: 'email', value: 'a@b.co' }, { type: 'sent', challenge: 'c' }, { type: 'signed-in' },
+      { type: 'refused', refusal: { kind: 'failed' } })
+
+    expect(state).toMatchObject({ step: 'email', challenge: null, refusal: { kind: 'failed' } })
+  })
+})

package/tests/step.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test'
+import { DEFAULT_ALIAS as AUTH_SERVICE } from '@owlmeans/client-auth'
+import type { LoginContext } from '@owlmeans/client-auth/login'
+import type { EmailPasswordStatusView } from '@owlmeans/auth-email'
+import { EMAIL_OFFER_LOGIN_STEP, EMAIL_OFFER_STEP_PRIORITY } from '../src/consts.js'
+import { emailOfferStep } from '../src/step.js'
+import { createEmailStorageHelper } from '../src/storage.js'
+import { memoryArea } from './helpers.js'
+
+const context = (userId: string | null): LoginContext => ({
+  service: (alias: string) => {
+    if (alias !== AUTH_SERVICE) {
+      throw new Error(`unexpected service ${alias}`)
+    }
+    return { user: () => { if (userId == null) throw new Error('signed out'); return { userId } } } as never
+  },
+}) as unknown as LoginContext
+
+const client = (status: EmailPasswordStatusView | Error) => {
+  let calls = 0
+  return {
+    calls: () => calls,
+    passwordStatus: async () => { calls++; if (status instanceof Error) throw status; return status },
+  }
+}
+
+const OPEN: EmailPasswordStatusView = { enabled: true, set: false, declined: false }
+
+describe('emailOfferStep — pending', () => {
+  test('sits below marketing consent and names the offer screen', () => {
+    const step = emailOfferStep(client(OPEN), 'auth-email:offer', createEmailStorageHelper({ session: () => memoryArea() }))
+
+    expect(step.alias).toBe(EMAIL_OFFER_LOGIN_STEP)
+    expect(step.entrypoint).toBe('auth-email:offer')
+    expect(step.priority).toBe(EMAIL_OFFER_STEP_PRIORITY)
+    expect(EMAIL_OFFER_STEP_PRIORITY).toBeLessThan(0)
+    expect(step.required).toBeUndefined()
+  })
+
+  test('no ticket: not pending, and the status is never read', async () => {
+    const reader = client(OPEN)
+    const step = emailOfferStep(reader, 'offer', createEmailStorageHelper({ session: () => memoryArea() }))
+
+    expect(await step.pending(context('account-1'))).toBe(false)
+    expect(reader.calls()).toBe(0)
+  })
+
+  test('a ticket and an enabled, unset, undeclined password: pending', async () => {
+    const session = memoryArea()
+    const storage = createEmailStorageHelper({ session: () => session })
+    storage.keepOffer('ticket', 'account-1')
+
+    expect(await emailOfferStep(client(OPEN), 'offer', storage).pending(context('account-1'))).toBe(true)
+    expect(storage.offer('account-1')).toBe('ticket')
+  })
+
+  test('a status that no longer allows the offer: not pending, and the ticket is forgotten', async () => {
+    for (const status of [
+      { ...OPEN, enabled: false }, { ...OPEN, set: true }, { ...OPEN, declined: true },
+    ]) {
+      const session = memoryArea()
+      const storage = createEmailStorageHelper({ session: () => session })
+      storage.keepOffer('ticket', 'account-1')
+      expect(storage.offer('account-1')).toBe('ticket')
+
+      expect(await emailOfferStep(client(status), 'offer', storage).pending(context('account-1'))).toBe(false)
+      expect(storage.offer()).toBeNull()
+    }
+  })
+
+  test('another account\'s ticket is not this sign-in\'s offer; a failing read throws for the host to fail open', async () => {
+    const session = memoryArea()
+    const storage = createEmailStorageHelper({ session: () => session })
+    storage.keepOffer('ticket', 'account-1')
+
+    expect(await emailOfferStep(client(OPEN), 'offer', storage).pending(context('account-2'))).toBe(false)
+    await expect(emailOfferStep(client(new Error('down')), 'offer', storage).pending(context('account-1')))
+      .rejects.toThrow('down')
+    // The ticket survives a broken read — it may still be used once the status answers.
+    expect(storage.offer('account-1')).toBe('ticket')
+  })
+})

package/tests/storage.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test'
+import { EMAIL_DEVICE_ID_PATTERN, EMAIL_OFFER_TTL_SECONDS } from '@owlmeans/auth-email'
+import { EMAIL_DEVICE_STORAGE, EMAIL_OFFER_STORAGE } from '../src/consts.js'
+import { createEmailStorageHelper } from '../src/storage.js'
+import { counting, memoryArea } from './helpers.js'
+
+const valid = new RegExp(EMAIL_DEVICE_ID_PATTERN)
+
+describe('emailStorageHelper — device id', () => {
+  test('creates 16 random bytes as 22 base64url characters, kept in localStorage', () => {
+    const local = memoryArea()
+    const helper = createEmailStorageHelper({ local: () => local, random: counting(250) })
+
+    const id = helper.deviceId()
+    expect(id).toHaveLength(22)
+    expect(id).toMatch(valid)
+    expect(id).not.toMatch(/[+/=]/)
+    expect(local.data.get(EMAIL_DEVICE_STORAGE)).toBe(id)
+  })
+
+  test('reuses the stored id, across helpers (a later page load)', () => {
+    const local = memoryArea()
+    const first = createEmailStorageHelper({ local: () => local, random: counting(1) }).deviceId()
+    const again = createEmailStorageHelper({ local: () => local, random: counting(99) }).deviceId()
+
+    expect(again).toBe(first)
+  })
+
+  test('replaces a stored value that is not a device id', () => {
+    const local = memoryArea()
+    local.data.set(EMAIL_DEVICE_STORAGE, 'not a device id')
+    const id = createEmailStorageHelper({ local: () => local, random: counting(7) }).deviceId()
+
+    expect(id).toMatch(valid)
+    expect(local.data.get(EMAIL_DEVICE_STORAGE)).toBe(id)
+  })
+
+  test('without storage, one ephemeral id for the life of the page', () => {
+    let calls = 0
+    const random = (count: number) => { calls++; return counting(calls)(count) }
+    const refusing = createEmailStorageHelper({ local: () => memoryArea(true), random })
+    const absent = createEmailStorageHelper({ local: () => null, random })
+
+    expect(refusing.deviceId()).toMatch(valid)
+    expect(refusing.deviceId()).toBe(refusing.deviceId())
+    expect(absent.deviceId()).toBe(absent.deviceId())
+    expect(calls).toBe(2)
+  })
+})
+
+describe('emailStorageHelper — offer ticket', () => {
+  test('keeps, reads and drops the ticket in sessionStorage', () => {
+    const session = memoryArea()
+    const helper = createEmailStorageHelper({ session: () => session })
+
+    expect(helper.offer()).toBeNull()
+    helper.keepOffer('ticket-1', 'account-1')
+    expect(session.data.has(EMAIL_OFFER_STORAGE)).toBe(true)
+    expect(helper.offer('account-1')).toBe('ticket-1')
+    expect(helper.offer()).toBe('ticket-1')
+    helper.dropOffer()
+    expect(helper.offer('account-1')).toBeNull()
+  })
+
+  test('an expired ticket, or another account\'s, is no offer', () => {
+    const session = memoryArea()
+    let now = 1_000_000
+    const helper = createEmailStorageHelper({ session: () => session, now: () => now })
+
+    helper.keepOffer('ticket-2', 'account-2')
+    expect(helper.offer('someone-else')).toBeNull()
+    now += EMAIL_OFFER_TTL_SECONDS * 1000
+    expect(helper.offer('account-2')).toBeNull()
+  })
+
+  test('a browser that refuses storage keeps no offer and throws nothing', () => {
+    const helper = createEmailStorageHelper({ session: () => memoryArea(true) })
+
+    expect(() => helper.keepOffer('ticket-3')).not.toThrow()
+    expect(helper.offer()).toBeNull()
+    expect(() => helper.dropOffer()).not.toThrow()
+  })
+})

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.react.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/",
+    "paths": {
+      "@/*": [
+        "./src/@/*"
+      ]
+    }
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
+  ]
+}