@owlmeans/client-auth 0.1.18-rc.44 → 0.1.18-rc.45

package/src/login/i18n/en.json

@@ -16,11 +16,15 @@
       "fallback": "Continue with {{method}}"
     },
     "terms": {
-      "agreement": "I have read and agree to the {{terms}} and the {{privacy}}.",
+      "accept": "I have read and agree to the {{documents}}.",
       "terms": "Terms & Conditions",
       "privacy": "Privacy Policy",
       "cookies": "Cookie Policy",
-      "required": "Please confirm the Terms & Conditions and the Privacy Policy to continue."
+      "billing": "Billing Terms",
+      "product": "{{product}} Product Terms",
+      "notice": "How we handle your personal data: {{notices}}.",
+      "revised": "Last updated: {{date}}",
+      "required": "Please confirm the {{documents}} to continue."
     },
     "consent": {
       "required": "Signing in stores a session cookie. Accept essential cookies to continue."

package/src/login/i18n/es.json

@@ -16,11 +16,15 @@
       "fallback": "Continuar con {{method}}"
     },
     "terms": {
-      "agreement": "He leído y acepto los {{terms}} y la {{privacy}}.",
+      "accept": "He leído y acepto {{documents}}.",
       "terms": "Términos y Condiciones",
       "privacy": "Política de Privacidad",
       "cookies": "Política de Cookies",
-      "required": "Confirma los Términos y Condiciones y la Política de Privacidad para continuar."
+      "billing": "Condiciones de Facturación",
+      "product": "Condiciones del Producto {{product}}",
+      "notice": "Cómo tratamos tus datos personales: {{notices}}.",
+      "revised": "Última actualización: {{date}}",
+      "required": "Confirma {{documents}} para continuar."
     },
     "consent": {
       "required": "Iniciar sesión guarda una cookie de sesión. Acepta las cookies esenciales para continuar."

package/src/login/i18n/fr.json

@@ -16,11 +16,15 @@
       "fallback": "Continuer avec {{method}}"
     },
     "terms": {
-      "agreement": "J’ai lu et j’accepte les {{terms}} et la {{privacy}}.",
+      "accept": "J’ai lu et j’accepte {{documents}}.",
       "terms": "conditions générales",
       "privacy": "politique de confidentialité",
       "cookies": "Politique relative aux cookies",
-      "required": "Confirmez les conditions générales et la politique de confidentialité pour continuer."
+      "billing": "Conditions de facturation",
+      "product": "Conditions du produit {{product}}",
+      "notice": "Comment nous traitons vos données personnelles : {{notices}}.",
+      "revised": "Dernière mise à jour : {{date}}",
+      "required": "Confirmez {{documents}} pour continuer."
     },
     "consent": {
       "required": "La connexion enregistre un cookie de session. Acceptez les cookies essentiels pour continuer."

package/src/login/i18n/pl.json

@@ -16,11 +16,15 @@
       "fallback": "Kontynuuj z {{method}}"
     },
     "terms": {
-      "agreement": "Przeczytałem(-am) i akceptuję {{terms}} oraz {{privacy}}.",
+      "accept": "Przeczytałem(-am) i akceptuję {{documents}}.",
       "terms": "Regulamin",
       "privacy": "Politykę prywatności",
       "cookies": "Politykę plików cookie",
-      "required": "Aby kontynuować, potwierdź Regulamin i Politykę prywatności."
+      "billing": "Warunki rozliczeń",
+      "product": "Warunki produktu {{product}}",
+      "notice": "Jak przetwarzamy Twoje dane osobowe: {{notices}}.",
+      "revised": "Ostatnia aktualizacja: {{date}}",
+      "required": "Aby kontynuować, potwierdź {{documents}}."
     },
     "consent": {
       "required": "Logowanie zapisuje plik cookie sesji. Zaakceptuj niezbędne pliki cookie, aby kontynuować."

package/src/login/i18n/ru.json

@@ -16,11 +16,15 @@
       "fallback": "Продолжить с {{method}}"
     },
     "terms": {
-      "agreement": "Я прочитал(а) и принимаю {{terms}} и {{privacy}}.",
+      "accept": "Я прочитал(а) и принимаю {{documents}}.",
       "terms": "Условия использования",
       "privacy": "Политику конфиденциальности",
       "cookies": "Политику файлов cookie",
-      "required": "Чтобы продолжить, подтвердите Условия использования и Политику конфиденциальности."
+      "billing": "Условия оплаты",
+      "product": "Условия использования продукта {{product}}",
+      "notice": "Как мы обрабатываем ваши персональные данные: {{notices}}.",
+      "revised": "Последнее обновление: {{date}}",
+      "required": "Чтобы продолжить, подтвердите {{documents}}."
     },
     "consent": {
       "required": "Вход сохраняет сессионный файл cookie. Примите необходимые файлы cookie, чтобы продолжить."

package/src/login/i18n/uk.json

@@ -16,11 +16,15 @@
       "fallback": "Продовжити з {{method}}"
     },
     "terms": {
-      "agreement": "Я прочитав(-ла) і приймаю {{terms}} та {{privacy}}.",
+      "accept": "Я прочитав(-ла) і приймаю {{documents}}.",
       "terms": "Умови користування",
       "privacy": "Політику конфіденційності",
       "cookies": "Політику файлів cookie",
-      "required": "Щоб продовжити, підтвердьте Умови користування та Політику конфіденційності."
+      "billing": "Умови оплати",
+      "product": "Умови продукту {{product}}",
+      "notice": "Як ми обробляємо ваші персональні дані: {{notices}}.",
+      "revised": "Востаннє оновлено: {{date}}",
+      "required": "Щоб продовжити, підтвердьте {{documents}}."
     },
     "consent": {
       "required": "Вхід зберігає сеансовий файл cookie. Прийміть необхідні файли cookie, щоб продовжити."

package/src/login/index.ts

@@ -7,9 +7,11 @@ export * from './adopt.js'
 export * from './methods.js'
 export * from './flow.js'
 export * from './resume.js'
+export * from './terms-config.js'
 export * from './terms.js'
 export * from './credit.js'
 export * from './surrogate.js'
 export * from './screen.js'
 export * from './service.js'
 export * from './hook.js'
+export * from './land.js'

package/src/login/land.ts

@@ -0,0 +1,186 @@
+import { useCallback } from 'react'
+import type { AuthService } from '@owlmeans/auth-common'
+import { DISPATCHER } from '@owlmeans/auth'
+import { HOME } from '@owlmeans/context'
+import { useContext, useNavigate } from '@owlmeans/client'
+import type { ClientContext } from '@owlmeans/client'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { resumeSuspendedFlow } from '@owlmeans/client-flow'
+import { DEFAULT_ALIAS as AUTH_ALIAS } from '../consts.js'
+import { ensureLoginService } from './service.js'
+import type { LandOptions, LoginContext, LoginLanding, LoginService } from './types.js'
+
+/**
+ * Bound on a single step's `pending` check, or a landing hook's `landed` call.
+ *
+ * A step/hook that hangs must never hang sign-in itself — both `continueLogin` and
+ * `landAfterLogin` treat a timeout exactly like a rejection: fail OPEN, never block.
+ */
+export const LOGIN_STEP_TIMEOUT = 5_000
+
+/** Where a browser records the last token a landing hook has already run for. */
+export const LOGIN_LANDED_STORAGE = '_owlmeans-login-landed'
+
+/**
+ * Race a promise against a bound, resolving `undefined` (never rejecting) on timeout.
+ *
+ * A synchronous throw from the wrapped call is turned into a rejection by the caller before this
+ * ever sees it, so the only two outcomes here are "settled in time" and "timed out".
+ */
+const withTimeout = async <T>(promise: Promise<T>, ms: number): Promise<T | undefined> => {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race<T | undefined>([
+      promise,
+      new Promise<undefined>(resolve => { timer = setTimeout(() => resolve(undefined), ms) }),
+    ])
+  } finally {
+    if (timer != null) {
+      clearTimeout(timer)
+    }
+  }
+}
+
+/**
+ * Run every registered landing hook, once per distinct token.
+ *
+ * The stored token is overwritten BEFORE the hooks run, not after: a hook that throws or hangs
+ * must never make the same token re-run the whole set on the next call, since surviving exactly
+ * that is what the bound-and-swallow contract is for. The raw token string is the marker rather
+ * than a digest of it — it never leaves the browser, and this package already keeps the terms
+ * acceptance marker the same way (`LOGIN_TERMS_STORAGE`).
+ */
+const runLandingHooks = async (
+  ctx: LoginContext, login: LoginService, timeout: number
+): Promise<void> => {
+  const auth = ctx.service<AuthService>(AUTH_ALIAS)
+  const token = await auth.authenticated()
+  if (token == null) {
+    return
+  }
+
+  let last: string | null = null
+  try {
+    last = window.localStorage.getItem(LOGIN_LANDED_STORAGE)
+  } catch {
+    // Storage can be unavailable (private modes, blocked cookies). Treated as "never landed",
+    // which just re-runs the hooks — the safe direction, same as the terms-acceptance marker.
+  }
+  if (last === token) {
+    return
+  }
+
+  try {
+    window.localStorage.setItem(LOGIN_LANDED_STORAGE, token)
+  } catch { /* nothing to remember if storage was never available */ }
+
+  for (const hook of login.landingHooks()) {
+    await withTimeout(Promise.resolve().then(() => hook.landed(ctx)), timeout).catch(() => undefined)
+  }
+}
+
+/**
+ * Where a finished sign-in should go: the first pending step, else a suspended flow, else the
+ * fallback (ordinarily `HOME`).
+ *
+ * Re-checks `env().surrogate` even though {@link landAfterLogin} already did — this function is
+ * also called directly (e.g. from {@link useContinueLogin}, after the surrogate window has
+ * already closed), and the check is cheap insurance either way: **no step and no landing hook
+ * ever runs inside the surrogate popup.** It has nothing of its own to collect and nowhere to
+ * navigate — the popup's own `DispatcherHOC` has no `navigate() → HOME` at all.
+ */
+export const continueLogin = async (ctx: LoginContext, opts?: LandOptions): Promise<LoginLanding> => {
+  const login = ensureLoginService(ctx)
+  if (login.env().surrogate) {
+    return { alias: DISPATCHER }
+  }
+
+  const timeout = opts?.stepTimeout ?? LOGIN_STEP_TIMEOUT
+  const auth = ctx.service<AuthService>(AUTH_ALIAS)
+  const token = await auth.authenticated()
+
+  if (token != null) {
+    const steps = login.steps()
+    let start = 0
+    if (opts?.after != null) {
+      const index = steps.findIndex(step => step.alias === opts.after)
+      if (index >= 0) {
+        start = index + 1
+      }
+    }
+
+    for (let i = start; i < steps.length; i++) {
+      const step = steps[i]
+      // Registration proves only that some module reached the bundle — the step's own screen may
+      // not be bound in this tree (an older target, a partial import). Skipped, never thrown.
+      if (!ctx.hasEntrypoint(step.entrypoint)) {
+        continue
+      }
+
+      // A step that throws or hangs must never block sign-in: fail OPEN, i.e. "not pending".
+      const pending = await withTimeout(
+        Promise.resolve().then(() => step.pending(ctx)), timeout
+      ).catch(() => false)
+
+      if (pending === true) {
+        return { alias: step.entrypoint, query: await step.query?.(ctx), step: step.alias }
+      }
+    }
+  }
+
+  if (opts?.resume !== false) {
+    const landing = await resumeSuspendedFlow(ctx as unknown as ClientContext)
+    if (landing != null) {
+      return { alias: landing.entrypoint, query: landing.query }
+    }
+  }
+
+  return opts?.fallback ?? { alias: HOME }
+}
+
+/**
+ * The whole post-sign-in landing decision: run any due landing hooks for a freshly seen token,
+ * then delegate to {@link continueLogin} for where the flow actually goes.
+ *
+ * This is what a plugin that just adopted a token calls in place of the old inline
+ * "`resumeSuspendedFlow` else `HOME`" — `DispatcherHOC`, the supervisor plugin and both Google
+ * plugins all replace their own copy of that logic with this one.
+ */
+export const landAfterLogin = async (ctx: LoginContext, opts?: LandOptions): Promise<LoginLanding> => {
+  const login = ensureLoginService(ctx)
+  // Never run a step or a landing hook while THIS document is the surrogate popup — see the note
+  // on `continueLogin`.
+  if (login.env().surrogate) {
+    return { alias: DISPATCHER }
+  }
+
+  await runLandingHooks(ctx, login, opts?.stepTimeout ?? LOGIN_STEP_TIMEOUT)
+
+  return continueLogin(ctx, opts)
+}
+
+/**
+ * The absolute URL a landing resolves to — the same shape the supervisor and Google plugins
+ * already build their own `window.location.href` from.
+ */
+export const landingUrl = async (ctx: LoginContext, landing: LoginLanding): Promise<string> =>
+  await ctx.entrypoint<ClientEntrypoint<string>>(landing.alias).url(
+    { params: landing.params, query: landing.query }, { absolute: true }
+  )
+
+/**
+ * For a component that runs its own post-login step (the marketing-consent screen, for one) to
+ * call once it is satisfied — moves the flow on to the next step, or the ordinary landing.
+ *
+ * Not async at the call site by accident of its own — it is a callback a component holds and
+ * fires later, so nothing here needs the synchronous-gesture discipline `useLogin`/`useLogout` do.
+ */
+export const useContinueLogin = (): ((opts?: LandOptions) => Promise<void>) => {
+  const context = useContext() as unknown as ClientContext
+  const nav = useNavigate()
+
+  return useCallback(async (opts?: LandOptions) => {
+    const landing = await continueLogin(context, opts)
+    await nav.go(landing.alias, { params: landing.params, query: landing.query })
+  }, [context, nav])
+}

package/src/login/screen.tsx

@@ -1,13 +1,46 @@
 import { useCallback, useState } from 'react'
-import type { CSSProperties, FC } from 'react'
+import type { CSSProperties, FC, ReactNode } from 'react'
 import { useContext } from '@owlmeans/client'
 import type { CommonConfig } from '@owlmeans/config'
 import type { LoginContext, LoginMethod, LoginScreenProps, LoginService } from './types.js'
 import { LOGIN_SERVICE } from './consts.js'
 import { primaryLoginMethod } from './methods.js'
-import { acceptTerms, resolveTerms, termsAccepted } from './terms.js'
+import { acceptTerms, resolveTerms, termsAccepted, termsSentence } from './terms.js'
+import type { ResolvedTermsDocument, TermsSentencePart } from './terms.js'
 import { resolveCredit } from './credit.js'
 
+/** The same English fallbacks `@owlmeans/web-panel`'s `LoginTerms` uses, kept in sync by hand. */
+const DEFAULT_LABEL: Record<string, string> = {
+  terms: 'Terms & Conditions',
+  privacy: 'Privacy Policy',
+  cookies: 'Cookie Policy',
+  billing: 'Billing Terms',
+  product: '{{product}} Product Terms',
+}
+
+const resolveLabelFor = (
+  translate: (key: string, defaultValue: string) => string, locale: string | undefined
+) => (doc: ResolvedTermsDocument): string => {
+  const fromMap = doc.labelMap != null
+    ? (locale != null ? doc.labelMap[locale] : undefined) ?? Object.values(doc.labelMap)[0]
+    : undefined
+  let label = doc.label ?? fromMap
+    ?? (doc.i18nKey != null ? translate(doc.i18nKey, DEFAULT_LABEL[doc.key] ?? doc.key) : doc.key)
+
+  if (doc.params != null) {
+    for (const [key, value] of Object.entries(doc.params)) {
+      label = label.split(`{{${key}}}`).join(value)
+    }
+  }
+
+  return label
+}
+
+const renderParts = (parts: TermsSentencePart[]): ReactNode =>
+  parts.map((part, index) => part.href != null
+    ? <a key={index} href={part.href} target="_blank" rel="noreferrer noopener">{part.text}</a>
+    : <span key={index}>{part.text}</span>)
+
 /**
  * The page the card sits in.
  *
@@ -56,6 +89,7 @@ export const FallbackLoginScreen: FC<LoginScreenProps> = props => {
   const env = login.env()
   const resolved = resolveTerms(props.terms ?? cfg?.terms)
   const credit = resolveCredit(cfg?.credit, brand, context.cfg.service)
+  const resolveLabel = resolveLabelFor(t, props.locale)
 
   const [accepted, setAccepted] = useState(() => termsAccepted(resolved))
   const [attempted, setAttempted] = useState(false)
@@ -105,26 +139,36 @@ export const FallbackLoginScreen: FC<LoginScreenProps> = props => {
       </button>)}
 
     {resolved != null && <p style={{ marginTop: '1rem', fontSize: '.875rem' }}>
+      {/* The ONLY place `data-login-terms` appears — never duplicated onto a second control. */}
       <label>
         <input
           type="checkbox" checked={accepted} data-login-terms
           onChange={event => onAccept(event.target.checked)}
         />{' '}
-        {t('login.terms.agreement', 'I have read and agree to the Terms & Conditions and the Privacy Policy.')}
+        {renderParts(termsSentence(
+          t('login.terms.accept', 'I have read and agree to the {{documents}}.'),
+          resolved, props.locale, resolveLabel
+        ))}
       </label>
-      {' '}
-      <a href={resolved.terms} target="_blank" rel="noreferrer noopener">
-        {t('login.terms.terms', 'Terms & Conditions')}
-      </a>
-      {' · '}
-      <a href={resolved.privacy} target="_blank" rel="noreferrer noopener">
-        {t('login.terms.privacy', 'Privacy Policy')}
-      </a>
     </p>}
 
-    {attempted && blocked && <p role="alert" style={{ color: '#b00', fontSize: '.875rem' }}>
-      {t('login.terms.required',
-        'Please confirm the Terms & Conditions and the Privacy Policy to continue.')}
+    {resolved?.revisedAt != null && <p data-login-revised style={{ fontSize: '.75rem', opacity: .7 }}>
+      {t('login.terms.revised', 'Last updated: {{date}}').split('{{date}}').join(resolved.revisedAt)}
+    </p>}
+
+    {/* Outside the checkbox's label: a privacy disclosure is not something it consents to. */}
+    {resolved != null && <p data-login-privacy style={{ fontSize: '.875rem' }}>
+      {renderParts(termsSentence(
+        t('login.terms.notice', 'How we handle your personal data: {{notices}}.'),
+        resolved, props.locale, resolveLabel
+      ))}
+    </p>}
+
+    {attempted && blocked && resolved != null && <p role="alert" style={{ color: '#b00', fontSize: '.875rem' }}>
+      {renderParts(termsSentence(
+        t('login.terms.required', 'Please confirm the {{documents}} to continue.'),
+        resolved, props.locale, resolveLabel
+      ))}
     </p>}
 
     {props.footer ?? <p style={{ marginTop: '2rem', fontSize: '.75rem', opacity: .7 }}>

package/src/login/service.ts

@@ -7,8 +7,8 @@ import { adoptToken, revokeToken } from './adopt.js'
 import { resolveLoginMethods } from './methods.js'
 import { LoginOutcome } from './types.js'
 import type {
-  LoginContext, LoginMethodSource, LoginNotifier, LoginPlugin, LoginPrecondition,
-  LoginScreenComponent, LoginService, LoginServiceAppend
+  LoginContext, LoginLandingHook, LoginMethodSource, LoginNotifier, LoginPlugin, LoginPrecondition,
+  LoginScreenComponent, LoginService, LoginServiceAppend, LoginStep
 } from './types.js'
 
 /**
@@ -33,6 +33,8 @@ export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService =>
   const plugins: LoginPlugin[] = []
   const preconditions: LoginPrecondition[] = []
   const methodSources: LoginMethodSource[] = []
+  const steps: LoginStep[] = []
+  const hooks: LoginLandingHook[] = []
   let screen: LoginScreenComponent | null = null
   let notifier: LoginNotifier | null = null
 
@@ -77,6 +79,28 @@ export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService =>
 
     registerNotifier: value => { notifier = value },
 
+    registerStep: (step: LoginStep) => {
+      const existing = steps.findIndex(candidate => candidate.alias === step.alias)
+      if (existing >= 0) {
+        steps.splice(existing, 1)
+      }
+      steps.push(step)
+      steps.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+    },
+
+    steps: () => [...steps],
+
+    onLanded: (hook: LoginLandingHook) => {
+      const existing = hooks.findIndex(candidate => candidate.alias === hook.alias)
+      if (existing >= 0) {
+        hooks.splice(existing, 1)
+      }
+      hooks.push(hook)
+      hooks.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+    },
+
+    landingHooks: () => [...hooks],
+
     plugin: env => {
       const environment = env ?? defaultLoginEnv()
       const plugin = plugins.find(

package/src/login/terms-config.ts

@@ -0,0 +1,49 @@
+/**
+ * Extra `LoginTermsConfig` fields, added by TypeScript module augmentation rather than by editing
+ * `@owlmeans/config` itself.
+ *
+ * `@owlmeans/config` has roughly 85 dependents, and every one of them sits in the same release
+ * closure — a config bump ripples through every package that pins a range against it, whether or
+ * not it touches sign-in. The fields below are needed by exactly one consumer family (the sign-in
+ * screen and its terms confirmation, all downstream of `@owlmeans/client-auth`), so they are
+ * declared here instead, merged onto the base interface by TypeScript's own declaration merging.
+ *
+ * This file must be part of whatever a consumer's own compilation actually loads, or the merge
+ * never happens — an ambient augmentation applies only once the compiler has read the file that
+ * declares it. `@owlmeans/client-auth/login`'s barrel (`./index.ts`) re-exports this module for
+ * exactly that reason, so ANY import from `@owlmeans/client-auth/login` — which every application
+ * wiring sign-in already has — pulls this augmentation into that program. An app that constructs a
+ * `LoginTermsConfig` literal in a file that imports NOTHING from `@owlmeans/client-auth/login`
+ * still benefits as long as some other file in the same `tsc` program does; if none does (an
+ * isolated leaf package that only ever imports `@owlmeans/config`), add
+ * `import type {} from '@owlmeans/client-auth/login'` to the file building the literal — an
+ * import with an empty type list, kept only to pull this file into that program's graph.
+ *
+ * `export {}` below is required, not decorative: without at least one top-level import/export this
+ * file is a SCRIPT to TypeScript, not a MODULE, and `declare module '@owlmeans/config'` inside a
+ * script augments the global scope instead of merging onto the named module's exports.
+ */
+declare module '@owlmeans/config' {
+  interface LoginTermsConfig {
+    /** `documents[].key` (or a custom document's own key) → the ISO date it was last revised. */
+    revisions?: Record<string, string>
+    /** Off by default. A bare string is `{ href }`. */
+    billing?: string | { href: string, revisedAt?: string } | false
+    /** Off by default. `name` is interpolated into the `login.terms.product` translation. */
+    product?: { name: string, href: string, revisedAt?: string } | false
+    /**
+     * Custom documents beyond terms/billing/product, in the order they are agreed to.
+     *
+     * `label` may be a locale map (`{ en: '...', fr: '...' }`) — resolved at RENDER time, by
+     * whichever renderer has the current locale, never here: this file stays locale-free.
+     */
+    documents?: Array<{
+      key: string, href: string, label?: string | Record<string, string>, i18nKey?: string,
+      revisedAt?: string,
+    }>
+    /** Show the latest revision date beneath the confirmation. Default false. */
+    showRevision?: boolean
+  }
+}
+
+export { }

package/src/login/types.ts

@@ -206,6 +206,13 @@ export interface LoginScreenProps {
    * reaches for an i18n provider crashes the whole render in an app mounted without one.
    */
   translate?: (key: string, defaultValue: string) => string
+  /**
+   * The current language, for `Intl.ListFormat` and a custom document's own locale-keyed label.
+   *
+   * A prop for the same reason `translate` is: a component that reaches for an i18n context
+   * directly crashes the whole render in an app mounted without one.
+   */
+  locale?: string
   /** Replace or reorder what the resolver produced. */
   methods?: LoginMethod[] | ((methods: LoginMethod[]) => LoginMethod[])
   terms?: LoginTermsConfig | false
@@ -258,6 +265,14 @@ export interface LoginService extends LazyService {
   screen: () => LoginScreenComponent | null
   /** See {@link LoginNotifier}. Replaces any previously registered notifier. */
   registerNotifier: (notifier: LoginNotifier) => void
+  /** Register a post-login step. Replace-by-alias, priority-sorted (higher first). */
+  registerStep: (step: LoginStep) => void
+  /** Every registered step, priority-sorted (higher first). */
+  steps: () => LoginStep[]
+  /** Register a hook that observes a freshly authenticated token. Replace-by-alias, priority-sorted. */
+  onLanded: (hook: LoginLandingHook) => void
+  /** Every registered landing hook, priority-sorted (higher first). */
+  landingHooks: () => LoginLandingHook[]
   // Facade — every method re-selects the plugin and delegates.
   // NOTE: these stay plain writable instance properties, never getters, so that alternative
   // implementations (e.g. a native login service) can monkey-patch them directly.
@@ -274,6 +289,73 @@ export interface LoginService extends LazyService {
   revoke: () => Promise<void>
 }
 
+/**
+ * A step to run after sign-in completes, before the ordinary landing.
+ *
+ * Registered by a package that must collect something from a freshly authenticated user before
+ * the application resumes wherever it was headed — the marketing-consent screen is the first
+ * consumer. `landAfterLogin`/`continueLogin` (./land.js) walk the registered steps in priority
+ * order and land on the first one whose `pending` resolves `true`.
+ */
+/**
+ * The value shape a landing's `params`/`query` carries.
+ *
+ * Matches `FlowPayload` (`@owlmeans/flow`) and the `AbstractRequest` params/query fields
+ * (`@owlmeans/entrypoint`) structurally, rather than the narrower `Record<string, string>`, so a
+ * `LoginLanding` can be built directly from either a `SuspendedLandingRecord`'s query or a
+ * dispatcher's own forwarded `params`/`query` without a lossy re-cast at every call site.
+ */
+export type LoginLandingParams = Record<string, string | number | boolean | undefined | null>
+
+export interface LoginStep {
+  alias: string
+  /** Higher runs first. Defaults to 0. */
+  priority?: number
+  /** Entrypoint alias to navigate to while this step is pending. */
+  entrypoint: string
+  /** Extra query parameters for the landing, alongside the step's own alias. */
+  query?: (ctx: LoginContext) => LoginLandingParams | undefined
+  /** Whether this step still has something to collect from the signed-in user. */
+  pending: (ctx: LoginContext) => Promise<boolean>
+}
+
+/** Where a finished sign-in (or a pending step) lands. */
+export interface LoginLanding {
+  alias: string
+  params?: LoginLandingParams
+  query?: LoginLandingParams
+  /** The step alias this landing came from, when it came from one. */
+  step?: string
+}
+
+/**
+ * Observes that a freshly authenticated token has landed — unlike {@link LoginStep}, it never
+ * blocks the landing, it only reacts to it, once per distinct token.
+ *
+ * MUST never throw uncaught: the caller (`landAfterLogin`) bounds and swallows every hook's
+ * failure, on a timeout as well as a rejection, so a broken hook can never block sign-in.
+ */
+export interface LoginLandingHook {
+  alias: string
+  priority?: number
+  landed: (ctx: LoginContext) => Promise<void>
+}
+
+/** Options for {@link LoginService.landAfterLogin}-shaped helpers (./land.js). */
+export interface LandOptions {
+  /** Where to land when nothing else claims the flow. Defaults to `{ alias: HOME }`. */
+  fallback?: LoginLanding
+  /** `false` skips `resumeSuspendedFlow` — the caller already has its own concrete destination. */
+  resume?: boolean
+  /** Skip every step up to and including this alias — the resume point for a step's re-entry. */
+  after?: string
+  /**
+   * Overrides the step/hook timeout for this call. Mainly for tests; production callers leave it
+   * at the default (`LOGIN_STEP_TIMEOUT`).
+   */
+  stepTimeout?: number
+}
+
 export interface LoginServiceAppend {
   login: () => LoginService
 }

package/src/manager/README.md

@@ -37,7 +37,7 @@ Comprehensive error handling for authentication scenarios:
 This manager is part of the `@owlmeans/client-auth` package:
 
 ```bash
-npm install @owlmeans/client-auth@^0.1.18-rc.44
+npm install @owlmeans/client-auth@^0.1.18-rc.45
 ```
 
 ## API Reference