@owlmeans/auth-email 0.0.0-stage → 0.1.19

package/src/entrypoints.ts

@@ -0,0 +1,117 @@
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import type { EntrypointOptions } from '@owlmeans/entrypoint'
+import { backend, frontend, route, RouteMethod } from '@owlmeans/route'
+import { GUARD_ED25519 } from '@owlmeans/auth-common'
+import {
+  EMAIL_AUTH_API_PATH, EMAIL_AUTH_BASE, EMAIL_AUTH_OFFER, EMAIL_AUTH_OFFER_PATH, EMAIL_AUTH_OPTIONS,
+  EMAIL_AUTH_PASSWORD, EMAIL_AUTH_PASSWORD_DECLINE, EMAIL_AUTH_PASSWORD_PIN, EMAIL_AUTH_PASSWORD_REMOVE,
+  EMAIL_AUTH_PASSWORD_SET, EMAIL_AUTH_PASSWORD_STATUS, EMAIL_AUTH_PIN, EMAIL_AUTH_SIGN_IN, EMAIL_AUTH_TECH,
+  EMAIL_AUTH_TECH_GATE, EMAIL_AUTH_TECH_PIN, EMAIL_AUTH_TECH_WAIVER,
+} from './consts.js'
+import {
+  EmailEmptyRequestSchema, EmailPasswordPinRequestSchema, EmailPasswordRemoveRequestSchema,
+  EmailPasswordSetRequestSchema, EmailPinRequestSchema, EmailSignInRequestSchema, EmailTechPinRequestSchema,
+} from './schemas.js'
+import type {
+  EmailAuthEntrypointOptions, EmailAuthEntrypoints, EmailAuthOptionsView, EmailChallengeView, EmailEmptyRequest,
+  EmailPasswordPinRequest, EmailPasswordRemoveRequest, EmailPasswordSetRequest, EmailPasswordStatusView,
+  EmailPinRequest, EmailSignInRequest, EmailSignInView, EmailTechPinRequest, EmailTechPinView, EmailTechWaiverView,
+} from './types.js'
+
+/**
+ * The e-mail sign-in surface:
+ *
+ * - the guest base (`opts.path`, default `/auth/email`, under `opts.parent`) carries NO guards —
+ *   `options` GET `/options`, `pin` POST `/pin`, `signIn` POST `/sign-in`;
+ * - `password` (`/password`, under the guest base or `opts.passwordParent`) acts on the caller's own
+ *   account, so it needs the application's session: `opts.guards` (+ `opts.gate`) or a guarded
+ *   `opts.passwordParent` — neither is a declaration error, not a runtime one. `status` GET `/`,
+ *   `pin` POST `/pin`, `set` POST `/set`, `remove` POST `/remove`, `decline` POST `/decline`;
+ * - `tech` (`/tech`, developer tooling) defaults to `GUARD_ED25519` + the `EMAIL_AUTH_TECH_GATE`
+ *   gate: `pin` POST `/pin`, `waiver` POST `/waiver`;
+ * - `offer`, the top-level sticky frontend screen of the post-sign-in password offer.
+ */
+export const makeEmailAuthProtocols = (opts: EmailAuthEntrypointOptions = {}): EmailAuthEntrypoints => {
+  if (opts.passwordParent == null && opts.guards == null) {
+    throw new SyntaxError('auth-email: the password routes need either a passwordParent or explicit guards')
+  }
+
+  const get = (alias: string, path: string, parent: EmailAuthEntrypoints['base']) =>
+    route(alias, path, backend({ parent, method: RouteMethod.GET }))
+  const post = (alias: string, path: string, parent: EmailAuthEntrypoints['base']) =>
+    route(alias, path, backend({ parent, method: RouteMethod.POST }))
+
+  const base = openProtocol(route(EMAIL_AUTH_BASE, opts.path ?? EMAIL_AUTH_API_PATH, backend({ parent: opts.parent })))
+
+  const passwordOptions: EntrypointOptions = {
+    ...(opts.guards != null ? { guards: opts.guards } : {}),
+    ...(opts.gate != null ? { gate: opts.gate } : {}),
+  }
+  const passwordBase = openProtocol(
+    route(EMAIL_AUTH_PASSWORD, '/password', backend({ parent: opts.passwordParent ?? base })), passwordOptions
+  )
+
+  const techBase = openProtocol(route(EMAIL_AUTH_TECH, '/tech', backend({ parent: base })), {
+    guards: opts.techGuards ?? [GUARD_ED25519],
+    gate: opts.techGate ?? { alias: EMAIL_AUTH_TECH_GATE },
+  })
+
+  return {
+    base,
+    options: protocol(get(EMAIL_AUTH_OPTIONS, '/options', base), contract(typed<EmailAuthOptionsView>())),
+    pin: protocol(
+      post(EMAIL_AUTH_PIN, '/pin', base),
+      contract.request({ body: typed<EmailPinRequest>(EmailPinRequestSchema) }, typed<EmailChallengeView>())
+    ),
+    signIn: protocol(
+      post(EMAIL_AUTH_SIGN_IN, '/sign-in', base),
+      contract.request({ body: typed<EmailSignInRequest>(EmailSignInRequestSchema) }, typed<EmailSignInView>())
+    ),
+    password: {
+      base: passwordBase,
+      status: protocol(
+        get(EMAIL_AUTH_PASSWORD_STATUS, '/', passwordBase), contract(typed<EmailPasswordStatusView>())
+      ),
+      pin: protocol(
+        post(EMAIL_AUTH_PASSWORD_PIN, '/pin', passwordBase),
+        contract.request(
+          { body: typed<EmailPasswordPinRequest>(EmailPasswordPinRequestSchema) }, typed<EmailChallengeView>()
+        )
+      ),
+      set: protocol(
+        post(EMAIL_AUTH_PASSWORD_SET, '/set', passwordBase),
+        contract.request(
+          { body: typed<EmailPasswordSetRequest>(EmailPasswordSetRequestSchema) }, typed<EmailPasswordStatusView>()
+        )
+      ),
+      remove: protocol(
+        post(EMAIL_AUTH_PASSWORD_REMOVE, '/remove', passwordBase),
+        contract.request(
+          { body: typed<EmailPasswordRemoveRequest>(EmailPasswordRemoveRequestSchema) },
+          typed<EmailPasswordStatusView>()
+        )
+      ),
+      decline: protocol(
+        post(EMAIL_AUTH_PASSWORD_DECLINE, '/decline', passwordBase),
+        contract.request({ body: typed<EmailEmptyRequest>(EmailEmptyRequestSchema) }, typed<EmailPasswordStatusView>())
+      ),
+    },
+    tech: {
+      base: techBase,
+      pin: protocol(
+        post(EMAIL_AUTH_TECH_PIN, '/pin', techBase),
+        contract.request({ body: typed<EmailTechPinRequest>(EmailTechPinRequestSchema) }, typed<EmailTechPinView>())
+      ),
+      waiver: protocol(
+        post(EMAIL_AUTH_TECH_WAIVER, '/waiver', techBase),
+        contract.request({ body: typed<EmailEmptyRequest>(EmailEmptyRequestSchema) }, typed<EmailTechWaiverView>())
+      ),
+    },
+    // A top-level frontend screen, `sticky` so the router keeps it regardless of `cfg.service`
+    // filtering — the same shape as marketing consent's screen.
+    offer: openProtocol(
+      route(EMAIL_AUTH_OFFER, opts.screen?.path ?? EMAIL_AUTH_OFFER_PATH, frontend({ parent: opts.screen?.parent })),
+      { sticky: true }
+    ),
+  }
+}

package/src/errors.ts

@@ -0,0 +1,78 @@
+import { ResilientError } from '@owlmeans/error'
+
+/**
+ * The e-mail sign-in error family, shared by the server that throws and the client that reads it
+ * back (each class is registered, so it survives the wire). A failed PIN or password check is
+ * `AuthenFailed` from `@owlmeans/auth`, never one of these: no answer here may tell an unknown
+ * address from a wrong credential.
+ */
+export class EmailAuthError extends ResilientError {
+  public static override typeName: string = 'EmailAuthError'
+
+  constructor(message: string = 'error') {
+    super(EmailAuthError.typeName, `auth-email:${message}`)
+  }
+}
+
+/** A password sign-in or a password route on a deployment that does not offer passwords. */
+export class EmailPasswordDisabled extends EmailAuthError {
+  public static override typeName: string = `${EmailAuthError.typeName}PasswordDisabled`
+  public static httpStatus = 404
+
+  constructor(message: string = 'password') {
+    super(`disabled:${message}`)
+    this.type = EmailPasswordDisabled.typeName
+  }
+}
+
+/** A new password the policy refuses (length bounds); the message names the rule. */
+export class EmailPasswordWeak extends EmailAuthError {
+  public static override typeName: string = `${EmailAuthError.typeName}PasswordWeak`
+  public static httpStatus = 422
+
+  constructor(message: string = 'length') {
+    super(`weak:${message}`)
+    this.type = EmailPasswordWeak.typeName
+  }
+}
+
+/** The one-use offer ticket is spent, expired or another account's — confirm with a PIN instead. */
+export class EmailOfferExpired extends EmailAuthError {
+  public static override typeName: string = `${EmailAuthError.typeName}OfferExpired`
+  public static httpStatus = 409
+
+  constructor(message: string = 'offer') {
+    super(`expired:${message}`)
+    this.type = EmailOfferExpired.typeName
+  }
+}
+
+/** A developer (tech) route on a deployment where they are off: answers as if it did not exist. */
+export class EmailTechDisabled extends EmailAuthError {
+  public static override typeName: string = `${EmailAuthError.typeName}TechDisabled`
+  public static httpStatus = 404
+
+  constructor(message: string = 'tech') {
+    super(`disabled:${message}`)
+    this.type = EmailTechDisabled.typeName
+  }
+}
+
+/** A store, mailer or captcha authority could not be consulted, so the request fails closed. */
+export class EmailAuthUnavailable extends EmailAuthError {
+  public static override typeName: string = `${EmailAuthError.typeName}Unavailable`
+  public static httpStatus = 503
+  public static allowServerErrorStatus = true
+
+  constructor(message: string = 'unavailable') {
+    super(`unavailable:${message}`)
+    this.type = EmailAuthUnavailable.typeName
+  }
+}
+
+ResilientError.registerErrorClass(EmailAuthError)
+ResilientError.registerErrorClass(EmailPasswordDisabled)
+ResilientError.registerErrorClass(EmailPasswordWeak)
+ResilientError.registerErrorClass(EmailOfferExpired)
+ResilientError.registerErrorClass(EmailTechDisabled)
+ResilientError.registerErrorClass(EmailAuthUnavailable)

package/src/index.ts

@@ -0,0 +1,5 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './schemas.js'
+export * from './errors.js'
+export * from './entrypoints.js'

package/src/schemas.ts

@@ -0,0 +1,95 @@
+import type { JSONSchemaType } from 'ajv'
+import {
+  EMAIL_ADDRESS_MAX_LENGTH, EMAIL_DEVICE_ID_PATTERN, EMAIL_LOCALE_MAX_LENGTH, EMAIL_PASSWORD_WIRE_MAX_LENGTH,
+  EMAIL_PIN_PATTERN, EMAIL_TOKEN_MAX_LENGTH, EmailPasswordPurpose,
+} from './consts.js'
+import type {
+  EmailEmptyRequest, EmailPasswordPinRequest, EmailPasswordRemoveRequest, EmailPasswordSetRequest,
+  EmailPinRequest, EmailSignInRequest, EmailTechPinRequest,
+} from './types.js'
+
+// Every request schema refuses unknown fields; no body carries an organization or a source.
+// The address is lowercased and trimmed by the server; the password policy is checked there too.
+
+const email = { type: 'string', format: 'email', minLength: 3, maxLength: EMAIL_ADDRESS_MAX_LENGTH } as const
+const device = { type: 'string', pattern: EMAIL_DEVICE_ID_PATTERN } as const
+const pin = { type: 'string', pattern: EMAIL_PIN_PATTERN } as const
+const token = { type: 'string', minLength: 1, maxLength: EMAIL_TOKEN_MAX_LENGTH } as const
+const password = { type: 'string', minLength: 1, maxLength: EMAIL_PASSWORD_WIRE_MAX_LENGTH } as const
+const locale = { type: 'string', minLength: 1, maxLength: EMAIL_LOCALE_MAX_LENGTH } as const
+
+export const EmailPinRequestSchema: JSONSchemaType<EmailPinRequest> = {
+  type: 'object',
+  properties: {
+    email,
+    locale: { ...locale, nullable: true },
+    captcha: { ...token, nullable: true },
+  },
+  required: ['email'],
+  additionalProperties: false,
+}
+
+/** One schema for both modes; the server enforces exactly one of PIN (`challenge` + `pin`) or `password`. */
+export const EmailSignInRequestSchema: JSONSchemaType<EmailSignInRequest> = {
+  type: 'object',
+  properties: {
+    email,
+    device,
+    challenge: { ...token, nullable: true },
+    pin: { ...pin, nullable: true },
+    password: { ...password, nullable: true },
+    captcha: { ...token, nullable: true },
+    locale: { ...locale, nullable: true },
+  },
+  required: ['email', 'device'],
+  additionalProperties: false,
+}
+
+export const EmailPasswordPinRequestSchema: JSONSchemaType<EmailPasswordPinRequest> = {
+  type: 'object',
+  properties: {
+    purpose: { type: 'string', enum: Object.values(EmailPasswordPurpose) },
+    locale: { ...locale, nullable: true },
+  },
+  required: ['purpose'],
+  additionalProperties: false,
+}
+
+export const EmailPasswordSetRequestSchema: JSONSchemaType<EmailPasswordSetRequest> = {
+  type: 'object',
+  properties: {
+    password,
+    offer: { ...token, nullable: true },
+    challenge: { ...token, nullable: true },
+    pin: { ...pin, nullable: true },
+    device: { ...device, nullable: true },
+  },
+  required: ['password'],
+  additionalProperties: false,
+}
+
+export const EmailPasswordRemoveRequestSchema: JSONSchemaType<EmailPasswordRemoveRequest> = {
+  type: 'object',
+  properties: {
+    challenge: token,
+    pin,
+    device: { ...device, nullable: true },
+  },
+  required: ['challenge', 'pin'],
+  additionalProperties: false,
+}
+
+export const EmailTechPinRequestSchema: JSONSchemaType<EmailTechPinRequest> = {
+  type: 'object',
+  properties: { challenge: token, pin },
+  required: ['challenge', 'pin'],
+  additionalProperties: false,
+}
+
+/** The body of `password/decline` and `tech/waiver`: an empty object. */
+export const EmailEmptyRequestSchema = {
+  type: 'object',
+  properties: {},
+  required: [],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<EmailEmptyRequest>

package/src/types.ts

@@ -0,0 +1,179 @@
+import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
+import type { RouteParent } from '@owlmeans/route'
+import type { EMAIL_AUTH_LOCALES, EMAIL_CAPTCHA_PROVIDER, EmailPasswordPurpose, EmailSignInReason } from './consts.js'
+
+/** One of the languages the sign-in mails are written in. */
+export type EmailAuthLocale = typeof EMAIL_AUTH_LOCALES[number]
+
+// --- Views (answers) ---------------------------------------------------------------------------
+
+/** The captcha a client must solve before send-PIN and password sign-in. */
+export interface EmailAuthCaptchaView {
+  provider: typeof EMAIL_CAPTCHA_PROVIDER
+  siteKey: string
+}
+
+/** `GET options` — what this deployment offers; asks for no address. */
+export interface EmailAuthOptionsView {
+  /** Password sign-in and the password routes are served. */
+  password: boolean
+  /** `null` when captcha is off (or a valid developer waiver came with the request). */
+  captcha: EmailAuthCaptchaView | null
+  pinLength: number
+}
+
+/** A PIN was mailed: the signed challenge to send back with it. */
+export interface EmailChallengeView {
+  challenge: string
+}
+
+/**
+ * `POST sign-in`. A signed-in answer carries `token` (and, after a PIN sign-in of a person without
+ * a password who has not declined one, the one-use `offer` ticket); a password sign-in on an
+ * unknown device carries `challenge` + `reason: device` instead — a PIN was mailed and the password
+ * was not checked.
+ */
+export interface EmailSignInView {
+  token?: string
+  offer?: string
+  challenge?: string
+  reason?: EmailSignInReason
+}
+
+/** The signed-in account's password state. */
+export interface EmailPasswordStatusView {
+  /** Passwords are enabled on this deployment. */
+  enabled: boolean
+  set: boolean
+  /** The person declined the post-sign-in offer (or removed their password). */
+  declined: boolean
+  /** ISO time of the last set/change/remove. */
+  updatedAt?: string
+}
+
+export interface EmailTechPinView {
+  ok: boolean
+}
+
+/** A developer waiver: send `waiver` in `EMAIL_WAIVER_HEADER` until `expiresAt` (ISO time). */
+export interface EmailTechWaiverView {
+  waiver: string
+  expiresAt: string
+}
+
+// --- Requests (bodies) -------------------------------------------------------------------------
+
+/** A body with no fields (decline, waiver). */
+export type EmailEmptyRequest = Record<string, never>
+
+/** `POST pin` — mail a sign-in PIN; the same answer for a known and a new address. */
+export interface EmailPinRequest {
+  email: string
+  locale?: string
+  captcha?: string
+}
+
+/**
+ * `POST sign-in` — ONE body for both modes: PIN mode sends `challenge` + `pin`, password mode
+ * sends `password` (+ `captcha`). The server accepts exactly one mode.
+ */
+export interface EmailSignInRequest {
+  email: string
+  /** The browser's device id (`EMAIL_DEVICE_ID_PATTERN`). */
+  device: string
+  challenge?: string
+  pin?: string
+  password?: string
+  captcha?: string
+  locale?: string
+}
+
+/** `POST password/pin` — mail a confirmation PIN to the account's own address. */
+export interface EmailPasswordPinRequest {
+  purpose: EmailPasswordPurpose
+  locale?: string
+}
+
+/**
+ * `POST password/set` — confirmed either by the `offer` ticket of a fresh PIN sign-in or by a
+ * `challenge` + `pin` from `password/pin`. `device` keeps the current browser remembered while the
+ * account's other devices are forgotten.
+ */
+export interface EmailPasswordSetRequest {
+  password: string
+  offer?: string
+  challenge?: string
+  pin?: string
+  device?: string
+}
+
+/** `POST password/remove` — confirmed by a `challenge` + `pin` from `password/pin`. */
+export interface EmailPasswordRemoveRequest {
+  challenge: string
+  pin: string
+  device?: string
+}
+
+/** `POST tech/pin` — a developer replaces the PIN of a pending challenge. */
+export interface EmailTechPinRequest {
+  challenge: string
+  pin: string
+}
+
+// --- Protocol tree -----------------------------------------------------------------------------
+
+export interface EmailAuthGateOption {
+  alias: string
+  params?: string | readonly string[]
+}
+
+/**
+ * The guest routes (`options`, `pin`, `sign-in`) are never guarded by this factory. The password
+ * routes need the application's session: `guards` (+ `gate`), or a `passwordParent` whose guards
+ * they inherit — neither is a declaration error. The developer (tech) routes default to
+ * `GUARD_ED25519` + the `EMAIL_AUTH_TECH_GATE` gate.
+ */
+export interface EmailAuthEntrypointOptions {
+  /** The guest base path; default `EMAIL_AUTH_API_PATH`. */
+  path?: string
+  /** The guest base's parent route. */
+  parent?: RouteParent
+  /** Guards of the password subtree. */
+  guards?: string | readonly string[]
+  /** Gate of the password subtree. */
+  gate?: EmailAuthGateOption
+  /** Mount the password subtree (`/password`) under this route instead of the guest base. */
+  passwordParent?: RouteParent
+  /** Guards of the tech subtree; default `[GUARD_ED25519]`. */
+  techGuards?: string | readonly string[]
+  /** Gate of the tech subtree; default `{ alias: EMAIL_AUTH_TECH_GATE }`. */
+  techGate?: EmailAuthGateOption
+  /** The offer screen; default path `EMAIL_AUTH_OFFER_PATH`, top-level. */
+  screen?: { path?: string, parent?: RouteParent }
+}
+
+export interface EmailPasswordEntrypoints {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  status: EntrypointProtocol<{}, EmailPasswordStatusView>
+  pin: EntrypointProtocol<{ body: EmailPasswordPinRequest }, EmailChallengeView>
+  set: EntrypointProtocol<{ body: EmailPasswordSetRequest }, EmailPasswordStatusView>
+  remove: EntrypointProtocol<{ body: EmailPasswordRemoveRequest }, EmailPasswordStatusView>
+  decline: EntrypointProtocol<{ body: EmailEmptyRequest }, EmailPasswordStatusView>
+}
+
+export interface EmailTechEntrypoints {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  pin: EntrypointProtocol<{ body: EmailTechPinRequest }, EmailTechPinView>
+  waiver: EntrypointProtocol<{ body: EmailEmptyRequest }, EmailTechWaiverView>
+}
+
+export interface EmailAuthEntrypoints {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  options: EntrypointProtocol<{}, EmailAuthOptionsView>
+  pin: EntrypointProtocol<{ body: EmailPinRequest }, EmailChallengeView>
+  signIn: EntrypointProtocol<{ body: EmailSignInRequest }, EmailSignInView>
+  password: EmailPasswordEntrypoints
+  tech: EmailTechEntrypoints
+  /** The post-sign-in "set a password" screen — frontend, sticky. */
+  offer: EntrypointProtocol<OpenRequest, OpenValue>
+}

package/tests/consts.spec.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test'
+import { ResilientError } from '@owlmeans/error'
+import * as email from '@owlmeans/auth-email'
+import {
+  EmailAuthError, EmailAuthUnavailable, EmailOfferExpired, EmailPasswordDisabled, EmailPasswordWeak,
+  EmailTechDisabled,
+} from '@owlmeans/auth-email'
+
+/** Server, browser and stored records agree on these values; a change here breaks one of them. */
+describe('@owlmeans/auth-email — constants', () => {
+  test('names the methods, token types, envelopes, header and captcha actions', () => {
+    expect(email.EMAIL_LOGIN_METHOD).toBe('email')
+    expect(email.EMAIL_PIN_AUTH_TYPE).toBe('email-pin')
+    expect(email.EMAIL_PASSWORD_AUTH_TYPE).toBe('email-password')
+    expect(email.EMAIL_CONFIRM_ENVELOPE).toBe('email-confirm')
+    expect(email.EMAIL_WAIVER_ENVELOPE).toBe('email-waiver')
+    expect(email.EMAIL_WAIVER_HEADER).toBe('x-owlmeans-email-waiver')
+    expect(email.EMAIL_CAPTCHA_ACTION_PIN).toBe('email_pin')
+    expect(email.EMAIL_CAPTCHA_ACTION_PASSWORD).toBe('email_password')
+    expect(email.EMAIL_CAPTCHA_PROVIDER).toBe('recaptcha-v3')
+    expect(email.EMAIL_IDENTITY_TYPE).toBe('email-otp')
+  })
+
+  test('pins the policy numbers and patterns', () => {
+    expect(email.EMAIL_PIN_LENGTH).toBe(6)
+    expect(email.EMAIL_PIN_PATTERN).toBe('^[0-9]{6}$')
+    expect(email.EMAIL_DEVICE_TTL_DAYS).toBe(30)
+    expect(email.EMAIL_DEVICE_LIMIT).toBe(10)
+    expect(email.EMAIL_DEVICE_ID_PATTERN).toBe('^[A-Za-z0-9_-]{22,64}$')
+    expect(email.EMAIL_OFFER_TTL_SECONDS).toBe(900)
+    expect(email.EMAIL_WAIVER_TTL_SECONDS).toBe(7200)
+    expect([email.EMAIL_PASSWORD_MIN_LENGTH, email.EMAIL_PASSWORD_MAX_LENGTH]).toEqual([8, 128])
+    expect([...email.EMAIL_AUTH_LOCALES]).toEqual(['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr'])
+    expect(Object.isFrozen(email.EMAIL_AUTH_LOCALES)).toBe(true)
+  })
+
+  test('pins the enums, service aliases and paths', () => {
+    expect(Object.values(email.EmailPasswordPurpose) as string[]).toEqual(['set', 'change', 'remove'])
+    expect(email.EmailSignInReason.Device as string).toBe('device')
+    expect(email.EMAIL_AUTH_SERVICE).toBe('auth-email')
+    expect(email.EMAIL_LOGIN_SERVICE).toBe('auth-email-client')
+    expect(email.EMAIL_AUTH_TECH_GATE).toBe('auth-email:tech-gate')
+    expect(email.EMAIL_AUTH_API_PATH).toBe('/auth/email')
+    expect(email.EMAIL_AUTH_OFFER_PATH).toBe('/login/password')
+  })
+})
+
+describe('@owlmeans/auth-email — errors', () => {
+  test('each class survives a marshal round trip with its type and status', () => {
+    const cases: Array<[ResilientError, Function, number]> = [
+      [new EmailPasswordDisabled(), EmailPasswordDisabled, 404],
+      [new EmailPasswordWeak('length'), EmailPasswordWeak, 422],
+      [new EmailOfferExpired(), EmailOfferExpired, 409],
+      [new EmailTechDisabled(), EmailTechDisabled, 404],
+      [new EmailAuthUnavailable('mail'), EmailAuthUnavailable, 503],
+    ]
+    for (const [error, Class, status] of cases) {
+      const restored = ResilientError.ensure(ResilientError.marshal(error))
+      expect(restored).toBeInstanceOf(Class)
+      expect(restored).toBeInstanceOf(EmailAuthError)
+      expect(restored.message).toBe(error.message)
+      expect((Class as unknown as { httpStatus: number }).httpStatus).toBe(status)
+    }
+    expect(new EmailPasswordWeak('length').message).toBe('auth-email:weak:length')
+  })
+})

package/tests/entrypoints.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from 'bun:test'
+import { protocols } from '@owlmeans/entrypoint'
+import type { EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import { AppType } from '@owlmeans/context'
+import { RouteMethod } from '@owlmeans/route'
+import { GUARD_ED25519 } from '@owlmeans/auth-common'
+import {
+  EMAIL_AUTH_BASE, EMAIL_AUTH_PASSWORD, EMAIL_AUTH_TECH, EMAIL_AUTH_TECH_GATE, makeEmailAuthProtocols,
+} from '@owlmeans/auth-email'
+import type { EmailAuthEntrypoints } from '@owlmeans/auth-email'
+
+const GUARDED = { guards: 'auth', gate: { alias: 'app:gate', params: ['owner'] } }
+
+const declarations = (tree: EmailAuthEntrypoints): EntrypointProtocolDeclaration[] => protocols(tree as never)
+
+/** The full path of a declaration: its parents' segments, then its own. */
+const pathOf = (tree: EmailAuthEntrypoints, declaration: EntrypointProtocolDeclaration): string => {
+  const byAlias = new Map(declarations(tree).map(entry => [entry.alias, entry]))
+  const segments: string[] = []
+  let current: EntrypointProtocolDeclaration | undefined = declaration
+  while (current != null) {
+    segments.unshift(current.route.route.path)
+    current = current.route.route.parent == null ? undefined : byAlias.get(current.route.route.parent)
+  }
+
+  return '/' + segments.map(segment => segment.replace(/^\/|\/$/g, '')).filter(Boolean).join('/')
+}
+
+describe('@owlmeans/auth-email — makeEmailAuthProtocols', () => {
+  test('builds every route with its alias, method and path', () => {
+    const tree = makeEmailAuthProtocols(GUARDED)
+    const routes = declarations(tree).filter(entry => entry !== tree.offer).map(entry => [
+      entry.alias, entry.route.route.method ?? RouteMethod.GET, pathOf(tree, entry),
+    ])
+
+    expect(routes).toEqual([
+      ['auth-email:base', RouteMethod.GET, '/auth/email'],
+      ['auth-email:options', RouteMethod.GET, '/auth/email/options'],
+      ['auth-email:pin', RouteMethod.POST, '/auth/email/pin'],
+      ['auth-email:sign-in', RouteMethod.POST, '/auth/email/sign-in'],
+      ['auth-email:password', RouteMethod.GET, '/auth/email/password'],
+      ['auth-email:password:status', RouteMethod.GET, '/auth/email/password'],
+      ['auth-email:password:pin', RouteMethod.POST, '/auth/email/password/pin'],
+      ['auth-email:password:set', RouteMethod.POST, '/auth/email/password/set'],
+      ['auth-email:password:remove', RouteMethod.POST, '/auth/email/password/remove'],
+      ['auth-email:password:decline', RouteMethod.POST, '/auth/email/password/decline'],
+      ['auth-email:tech', RouteMethod.GET, '/auth/email/tech'],
+      ['auth-email:tech:pin', RouteMethod.POST, '/auth/email/tech/pin'],
+      ['auth-email:tech:waiver', RouteMethod.POST, '/auth/email/tech/waiver'],
+    ])
+    expect(new Set(declarations(tree).map(entry => entry.alias)).size).toBe(14)
+  })
+
+  test('the guest routes carry no guards; password and tech carry theirs for their children', () => {
+    const tree = makeEmailAuthProtocols(GUARDED)
+
+    for (const guest of [tree.base, tree.options, tree.pin, tree.signIn]) {
+      expect(guest.guards).toEqual([])
+      expect(guest.gate).toBeUndefined()
+    }
+    expect(tree.password.base.guards).toEqual(['auth'])
+    expect(tree.password.base.gate).toEqual({ alias: 'app:gate', params: ['owner'] })
+    expect(tree.password.set.route.route.parent).toBe(EMAIL_AUTH_PASSWORD)
+    expect(tree.tech.base.guards).toEqual([GUARD_ED25519])
+    expect(tree.tech.base.gate).toEqual({ alias: EMAIL_AUTH_TECH_GATE, params: [] })
+    expect(tree.tech.waiver.route.route.parent).toBe(EMAIL_AUTH_TECH)
+  })
+
+  test('a passwordParent stands in for guards; path, parent and tech guards are overridable', () => {
+    const tree = makeEmailAuthProtocols({
+      path: '/email', parent: 'app:api', passwordParent: 'app:account',
+      techGuards: 'guard:dev', techGate: { alias: 'dev:gate' },
+    })
+
+    expect(tree.base.route.route.path).toBe('/email')
+    expect(tree.base.route.route.parent).toBe('app:api')
+    expect(tree.password.base.route.route.parent).toBe('app:account')
+    expect(tree.password.base.guards).toEqual([])
+    expect(tree.signIn.route.route.parent).toBe(EMAIL_AUTH_BASE)
+    expect(tree.tech.base.guards).toEqual(['guard:dev'])
+    expect(tree.tech.base.gate).toEqual({ alias: 'dev:gate', params: [] })
+  })
+
+  test('without guards or a passwordParent the declaration fails', () => {
+    expect(() => makeEmailAuthProtocols()).toThrow(SyntaxError)
+    expect(() => makeEmailAuthProtocols({ gate: { alias: 'app:gate' } })).toThrow(/passwordParent or explicit guards/)
+  })
+
+  test('the offer screen is a top-level sticky frontend route', () => {
+    const tree = makeEmailAuthProtocols(GUARDED)
+    const moved = makeEmailAuthProtocols({ ...GUARDED, screen: { path: '/welcome/password', parent: 'app:home' } })
+
+    expect(tree.offer.alias).toBe('auth-email:offer')
+    expect(tree.offer.sticky).toBe(true)
+    expect(tree.offer.route.route.type).toBe(AppType.Frontend)
+    expect(tree.offer.route.route.path).toBe('/login/password')
+    expect(tree.offer.route.route.parent).toBeUndefined()
+    expect(moved.offer.route.route.path).toBe('/welcome/password')
+    expect(moved.offer.route.route.parent).toBe('app:home')
+  })
+})