@owlmeans/client-auth 0.1.18-rc.9 → 0.1.18

package/src/login/terms.ts

@@ -0,0 +1,315 @@
+import { OWLMEANS_COOKIES_URL, OWLMEANS_PRIVACY_URL, OWLMEANS_TERMS_URL, type LoginTermsConfig } from '@owlmeans/config'
+import { LOGIN_SERVICE, LOGIN_TERMS_STORAGE } from './consts.js'
+import type { LoginContext, LoginService } from './types.js'
+import type {
+  LoginTermsAcceptance, LoginTermsHelper, ResolvedTerms, ResolvedTermsDocument, TermsSentencePart
+} from './terms/types.js'
+import './terms-config.js'
+import { DEFAULT_LABEL } from './consts.local.js'
+
+export const createLoginTermsHelper = (): LoginTermsHelper => {
+  /**
+   * A stable identity for one set of documents.
+   *
+   * Acceptance is recorded against it, so changing a URL — or a revision date, or adding a document
+   * — re-asks. Cheap and order-independent rather than cryptographic; it only has to change when the
+   * content pointer does.
+   *
+   * With no billing/product/custom documents and no revisions configured, this MUST produce the same
+   * digest as before this file grew those fields: `digest([terms, privacy, cookies])`. `terms.spec.ts`
+   * pins that byte-identity so no existing user is silently asked to re-accept.
+   */
+  const digest = (parts: string[]): string => {
+    let hash = 0
+    for (const char of parts.join(' ')) {
+      hash = ((hash << 5) - hash + char.charCodeAt(0)) | 0
+    }
+
+    return (hash >>> 0).toString(36)
+  }
+
+  const withRevisedAt = (
+    doc: Omit<ResolvedTermsDocument, 'revisedAt'>, revisedAt: string | undefined
+  ): ResolvedTermsDocument => revisedAt != null ? { ...doc, revisedAt } : doc
+
+  const resolveTerms = (cfg?: LoginTermsConfig | false): ResolvedTerms | null => {
+    if (cfg === false) {
+      return null
+    }
+    const terms = cfg?.terms ?? OWLMEANS_TERMS_URL
+    const privacy = cfg?.privacy ?? OWLMEANS_PRIVACY_URL
+    const cookies = cfg?.cookies ?? OWLMEANS_COOKIES_URL
+
+    const documents: ResolvedTermsDocument[] = [
+      withRevisedAt(
+        { key: 'terms', href: terms, i18nKey: 'login.terms.terms' }, cfg?.revisions?.terms
+      ),
+    ]
+
+    if (cfg?.billing) {
+      const billing = typeof cfg.billing === 'string' ? { href: cfg.billing } : cfg.billing
+      documents.push(withRevisedAt(
+        { key: 'billing', href: billing.href, i18nKey: 'login.terms.billing' },
+        cfg?.revisions?.billing ?? billing.revisedAt
+      ))
+    }
+
+    if (cfg?.product) {
+      documents.push(withRevisedAt(
+        {
+          key: 'product', href: cfg.product.href, i18nKey: 'login.terms.product',
+          params: { product: cfg.product.name },
+        },
+        cfg.product.revisedAt ?? cfg?.revisions?.product
+      ))
+    }
+
+    for (const custom of cfg?.documents ?? []) {
+      documents.push(withRevisedAt(
+        {
+          key: custom.key, href: custom.href,
+          ...(typeof custom.label === 'string' ? { label: custom.label } : {}),
+          ...(custom.label != null && typeof custom.label !== 'string' ? { labelMap: custom.label } : {}),
+          ...(custom.i18nKey != null ? { i18nKey: custom.i18nKey } : {}),
+        },
+        custom.revisedAt ?? cfg?.revisions?.[custom.key]
+      ))
+    }
+
+    // Cookies is disclosed as ITS OWN notice only when the app named a cookie policy explicitly, or
+    // when terms/privacy/cookies are ALL still the OwlMeans defaults — never as a silent extra on an
+    // app that customized terms and privacy but left cookies unset.
+    const allDefault = terms === OWLMEANS_TERMS_URL && privacy === OWLMEANS_PRIVACY_URL
+      && cookies === OWLMEANS_COOKIES_URL
+    const includeCookies = cfg?.cookies != null || allDefault
+
+    const notices: ResolvedTermsDocument[] = [
+      withRevisedAt({ key: 'privacy', href: privacy, i18nKey: 'login.terms.privacy' }, cfg?.revisions?.privacy),
+      ...(includeCookies
+        ? [withRevisedAt({ key: 'cookies', href: cookies, i18nKey: 'login.terms.cookies' }, cfg?.revisions?.cookies)]
+        : []),
+    ]
+
+    // The digest input for a plain config (no billing/product/custom/revisions) is BYTE-IDENTICAL to
+    // the pre-existing `[terms, privacy, cookies]` — see `terms.spec.ts`.
+    const digestInput = [terms, privacy, cookies]
+    for (const doc of documents) {
+      if (doc.key !== 'terms') {
+        digestInput.push(`${doc.key}=${doc.href}`)
+      }
+    }
+    for (const doc of [...documents, ...notices]) {
+      if (doc.revisedAt != null) {
+        digestInput.push(`${doc.key}@${doc.revisedAt}`)
+      }
+    }
+
+    const showRevision = cfg?.showRevision === true
+    const revisedAtValues = documents
+      .map(doc => doc.revisedAt)
+      .filter((value): value is string => value != null)
+    const revisedAt = showRevision && revisedAtValues.length > 0
+      ? revisedAtValues.reduce((max, value) => value > max ? value : max)
+      : undefined
+
+    return {
+      required: cfg?.required ?? true,
+      terms, privacy, cookies,
+      version: cfg?.version ?? digest(digestInput),
+      // Translations are alternate destinations for this canonical revision, not a new agreement.
+      documents: documents.map(doc => withLocalizedHrefs(doc, cfg)),
+      notices: notices.map(doc => withLocalizedHrefs(doc, cfg)),
+      showRevision,
+      ...(revisedAt != null ? { revisedAt } : {}),
+    }
+  }
+
+  const withLocalizedHrefs = (doc: ResolvedTermsDocument, cfg?: LoginTermsConfig): ResolvedTermsDocument => {
+    const hrefMap = cfg?.localizedHrefs?.[doc.key]
+
+    return hrefMap != null ? { ...doc, hrefMap } : doc
+  }
+
+  const termsHrefOf = (doc: ResolvedTermsDocument, locale?: string): string => {
+    const localized = locale != null
+      ? doc.hrefMap?.[locale] ?? doc.hrefMap?.[locale.toLowerCase()]
+        ?? doc.hrefMap?.[locale.split('-')[0].toLowerCase()]
+      : undefined
+
+    return typeof localized === 'string' && localized.trim() !== '' ? localized : doc.href
+  }
+
+  const termsAccepted = (resolved: ResolvedTerms | null): boolean => {
+    if (resolved == null || !resolved.required) {
+      return true
+    }
+    try {
+      return window.localStorage.getItem(LOGIN_TERMS_STORAGE) === resolved.version
+    } catch {
+      // Storage can be unavailable (private modes, blocked cookies). Refusing to remember is not
+      // refusing to proceed: the user is asked again, every time, which is the safe direction.
+      return false
+    }
+  }
+
+  const acceptTerms = (resolved: ResolvedTerms | null, accepted: boolean): void => {
+    if (resolved == null) {
+      return
+    }
+    try {
+      if (accepted) {
+        window.localStorage.setItem(LOGIN_TERMS_STORAGE, resolved.version)
+      } else {
+        window.localStorage.removeItem(LOGIN_TERMS_STORAGE)
+      }
+    } catch { /* nothing to remember if storage was never available */ }
+  }
+
+  const termsLabelResolver = (
+    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 termsAcceptanceOf = (
+    resolved: Pick<ResolvedTerms, 'documents' | 'notices' | 'version'>, locale?: string
+  ): LoginTermsAcceptance => ({
+    documents: resolved.documents.map(doc => ({ key: doc.key, href: termsHrefOf(doc, locale), revisedAt: doc.revisedAt })),
+    notices: resolved.notices.map(doc => ({ key: doc.key, href: termsHrefOf(doc, locale), revisedAt: doc.revisedAt })),
+    version: resolved.version,
+    ...(locale != null ? { locale } : {}),
+  })
+
+  const termsDeferred = (ctx: LoginContext): boolean =>
+    ctx.hasService(LOGIN_SERVICE)
+    && ctx.service<LoginService>(LOGIN_SERVICE).steps()
+      .some(step => step.confirmsTerms === true && ctx.hasEntrypoint(step.entrypoint))
+
+  /**
+   * Format a list of documents into sentence parts, via `Intl.ListFormat` when it exists ("A, B and
+   * C" in the caller's own locale and conjunction word), falling back to a plain ", "/" and " join
+   * when it does not (an old runtime with no `Intl.ListFormat`).
+   */
+  const formatDocumentList = (
+    docs: ResolvedTermsDocument[], locale: string | undefined, resolveLabel: (doc: ResolvedTermsDocument) => string
+  ): TermsSentencePart[] => {
+    if (docs.length < 1) {
+      return []
+    }
+    const labels = docs.map(resolveLabel)
+
+    if (typeof Intl !== 'undefined' && typeof Intl.ListFormat === 'function') {
+      let cursor = 0
+      const formatter = new Intl.ListFormat(locale, { style: 'long', type: 'conjunction' })
+
+      return formatter.formatToParts(labels).map(part => {
+        if (part.type === 'element') {
+          const doc = docs[cursor++]
+
+          return { text: part.value, href: termsHrefOf(doc, locale), documentKey: doc.key }
+        }
+
+        return { text: part.value }
+      })
+    }
+
+    const parts: TermsSentencePart[] = []
+    docs.forEach((doc, index) => {
+      if (index > 0) {
+        parts.push({ text: index === docs.length - 1 ? ' and ' : ', ' })
+      }
+      parts.push({ text: labels[index], href: termsHrefOf(doc, locale), documentKey: doc.key })
+    })
+
+    return parts
+  }
+
+  const termsSentence = (
+    template: string,
+    resolved: Pick<ResolvedTerms, 'documents' | 'notices'>,
+    locale: string | undefined,
+    resolveLabel: (doc: ResolvedTermsDocument) => string
+  ): TermsSentencePart[] => {
+    const byKey = (key: string): ResolvedTermsDocument | undefined =>
+      resolved.documents.find(doc => doc.key === key) ?? resolved.notices.find(doc => doc.key === key)
+
+    const placeholder = /\{\{(documents|notices|terms|privacy|cookies)\}\}/g
+    const parts: TermsSentencePart[] = []
+    let lastIndex = 0
+    let match: RegExpExecArray | null
+
+    while ((match = placeholder.exec(template)) != null) {
+      if (match.index > lastIndex) {
+        parts.push({ text: template.slice(lastIndex, match.index) })
+      }
+
+      const token = match[1]
+      if (token === 'documents') {
+        parts.push(...formatDocumentList(resolved.documents, locale, resolveLabel))
+      } else if (token === 'notices') {
+        parts.push(...formatDocumentList(resolved.notices, locale, resolveLabel))
+      } else {
+        const doc = byKey(token)
+        if (doc != null) {
+          parts.push({ text: resolveLabel(doc), href: termsHrefOf(doc, locale), documentKey: doc.key })
+        }
+      }
+
+      lastIndex = placeholder.lastIndex
+    }
+    if (lastIndex < template.length) {
+      parts.push({ text: template.slice(lastIndex) })
+    }
+
+    return parts
+  }
+
+  return {
+    resolveTerms, termsAccepted, acceptTerms, termsLabelResolver, termsHrefOf, termsAcceptanceOf, termsDeferred, termsSentence,
+  }
+}
+
+export const loginTermsHelper = createLoginTermsHelper()
+
+/** @deprecated compat:factory-refactor — use `loginTermsHelper.resolveTerms(…)` */
+export const resolveTerms = (cfg?: LoginTermsConfig | false): ResolvedTerms | null => loginTermsHelper.resolveTerms(cfg)
+
+/** @deprecated compat:factory-refactor — use `loginTermsHelper.termsAccepted(…)` */
+export const termsAccepted = (resolved: ResolvedTerms | null): boolean => loginTermsHelper.termsAccepted(resolved)
+
+/** @deprecated compat:factory-refactor — use `loginTermsHelper.acceptTerms(…)` */
+export const acceptTerms = (resolved: ResolvedTerms | null, accepted: boolean): void =>
+  loginTermsHelper.acceptTerms(resolved, accepted)
+
+/** @deprecated compat:factory-refactor — use `loginTermsHelper.termsLabelResolver(…)` */
+export const termsLabelResolver = (
+  translate: (key: string, defaultValue: string) => string, locale: string | undefined
+): ((doc: ResolvedTermsDocument) => string) => loginTermsHelper.termsLabelResolver(translate, locale)
+
+/** @deprecated compat:factory-refactor — use `loginTermsHelper.termsAcceptanceOf(…)` */
+export const termsAcceptanceOf = (
+  resolved: Pick<ResolvedTerms, 'documents' | 'notices' | 'version'>, locale?: string
+): LoginTermsAcceptance => loginTermsHelper.termsAcceptanceOf(resolved, locale)
+
+/** @deprecated compat:factory-refactor — use `loginTermsHelper.termsDeferred(…)` */
+export const termsDeferred = (ctx: LoginContext): boolean => loginTermsHelper.termsDeferred(ctx)
+
+/** @deprecated compat:factory-refactor — use `loginTermsHelper.termsSentence(…)` */
+export const termsSentence = (
+  template: string,
+  resolved: Pick<ResolvedTerms, 'documents' | 'notices'>,
+  locale: string | undefined,
+  resolveLabel: (doc: ResolvedTermsDocument) => string
+): TermsSentencePart[] => loginTermsHelper.termsSentence(template, resolved, locale, resolveLabel)

package/src/login/types.ts

@@ -1,4 +1,7 @@
+import type { ComponentType, CSSProperties, ReactNode } from 'react'
 import type { LazyService, BasicContext } from '@owlmeans/context'
+import type { LoginMethodEmphasis, LoginScreenConfig, LoginTermsConfig } from '@owlmeans/config'
+import { LoginOutcome } from './consts.js'
 
 /**
  * The context a login plugin is handed.
@@ -27,22 +30,6 @@ export interface LoginEnv {
   hasOpener: boolean
 }
 
-/** What a stage did, and therefore what the caller must do next. */
-export enum LoginOutcome {
-  /** The plugin took the flow over and it is finished. The caller does nothing more. */
-  Handled = 'handled',
-  /** The plugin did nothing — the caller carries on with its ordinary continuation. */
-  Passed = 'passed',
-  /** The browser is leaving this document. The caller must not navigate or render. */
-  Redirected = 'redirected',
-  /** Cannot proceed without a fresh user gesture — the caller renders a sign-in control. */
-  Gesture = 'gesture',
-  /** Authenticated, but with no channel back to the window that started the flow. */
-  Orphaned = 'orphaned',
-  /** The attempt ended with no token (blocked window, user closed it, provider refused). */
-  Failed = 'failed',
-}
-
 export interface LoginRequest {
   /** Where the login flow starts — a resolved dispatcher path, or the current address. */
   url: string
@@ -52,10 +39,28 @@ export interface LoginRequest {
    * fallback is a full page load of {@link url}.
    */
   navigate?: () => void | Promise<void>
-  /** Entrypoint alias to return to after login. */
+  /**
+   * Entrypoint alias to land on once sign-in completes.
+   *
+   * The facade parks it (`suspendLanding` from `@owlmeans/client-flow`, the record
+   * `resumeSuspendedFlow` reads) once the preconditions have passed, and holds {@link navigate}
+   * until the write has landed — so the continuation still goes to the dispatcher, whose ordinary
+   * post-sign-in landing (`landAfterLogin`: landing hooks, pending steps such as a consent screen,
+   * then the suspended landing) ends on this screen. It is never a navigation target of its own:
+   * a guarded screen reached before sign-in renders signed out. An attempt that ends without a
+   * sign-in (`Blocked`, `Failed`, `Gesture`) discards the parked screen again. A caller with no
+   * {@link navigate} leaves the document at once, so its parked screen is best-effort only.
+   */
   target?: string
 }
 
+export interface LogoutRequest {
+  /** Where a surrogate logout runs — a resolved surrogate path. */
+  url: string
+  /** The in-app continuation once the local session is gone. */
+  navigate?: () => void | Promise<void>
+}
+
 /**
  * A pluggable login mechanic — WHERE the authorization round trip runs.
  *
@@ -95,14 +100,161 @@ export interface LoginPlugin {
 
   /** A bearer token was issued in this document — decide where it goes. */
   complete: (ctx: LoginContext, token: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /**
+   * This document ALREADY holds a session — decide whether it is useful here.
+   *
+   * Absent means `Passed`: keep it and carry on, which is what an ordinary tab has always done.
+   * A surrogate hands it back to its opener instead, which is the whole point: a popup that
+   * discovers an existing session must sign the framed application in, not display the
+   * application to itself.
+   *
+   * Deliberately not `complete`: "a token was just issued here" and "a token was already here"
+   * are different facts, and a silent-refresh plugin will need to tell them apart.
+   */
+  resume?: (ctx: LoginContext, token: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /**
+   * Start logout from a user gesture.
+   *
+   * MUST open any window synchronously, for exactly the reason `begin` must — logging out of a
+   * framed application opens a window too. Implement as a NON-async function.
+   */
+  logout?: (ctx: LoginContext, request: LogoutRequest, env: LoginEnv) => Promise<LoginOutcome>
+
+  /** The local session is gone in this document — decide what to tell whom. */
+  logoutComplete?: (ctx: LoginContext, env: LoginEnv) => Promise<LoginOutcome>
+}
+
+/**
+ * Something that must be true before a login flow may start.
+ *
+ * SYNCHRONOUS on purpose. `begin` must not cross a microtask boundary before a plugin's
+ * `window.open`, or the popup blocker eats the window. A precondition that has to ask a server
+ * belongs somewhere else entirely.
+ *
+ * Returning false stops the flow and resolves `begin` as {@link LoginOutcome.Gesture} — which
+ * already means "cannot proceed without a fresh user gesture; render a control", and is exactly
+ * the state a user is in after a blocking dialog has opened over the page.
+ */
+export interface LoginPrecondition {
+  alias: string
+  /** Higher runs first. Defaults to 0. */
+  priority?: number
+  check: (ctx: LoginContext, request: LoginRequest, env: LoginEnv) => boolean
+}
+
+/** What a source needs in order to describe the methods it offers. */
+export interface LoginMethodContext {
+  context: LoginContext
+  env: LoginEnv
+  /** In-app navigation, when a component supplied it. */
+  navigate?: (alias: string, params?: Record<string, string>) => void | Promise<void>
+}
+
+/**
+ * One way to sign in, as the screen renders it.
+ *
+ * `start` is what a button calls. It MUST be callable synchronously from a click — branch on
+ * `env.embedded && !env.surrogate` first and open any window before the first `await`.
+ */
+export interface LoginMethod {
+  id: string
+  /** Set when an `AuthenticationPlugin` drives this method. */
+  type?: string
+  label?: string
+  i18nKey?: string
+  icon?: string
+  order?: number
+  emphasis?: LoginMethodEmphasis
+  restricted?: boolean
+  params?: Record<string, string>
+  start: (ctx: LoginMethodContext) => Promise<LoginOutcome>
+}
+
+export interface LoginMethodSource {
+  alias: string
+  list: (ctx: LoginMethodContext) => LoginMethod[]
 }
 
+/** What every rendering of the sign-in screen accepts, whatever its UI family. */
+export interface LoginScreenProps {
+  /** The one thing a consuming application is expected to supply. */
+  Logo?: ComponentType<{ className?: string }> | ReactNode
+  title?: ReactNode
+  subtitle?: ReactNode
+  /**
+   * `(key, defaultValue) => string`. A prop, never an implicit context read: a component that
+   * 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`, locale-keyed document labels and explicit hrefs.
+   *
+   * 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
+  config?: LoginScreenConfig
+  /** Replaces the composed credit line entirely. */
+  footer?: ReactNode
+  className?: string
+  containerClassName?: string
+  /**
+   * Inline overrides for the screen's outer box.
+   *
+   * It exists because the outer box carries its viewport height inline rather than as a utility
+   * class, and an escape hatch that a class can no longer provide has to be provided some other
+   * way. See the note on the screen itself.
+   */
+  style?: CSSProperties
+}
+
+export type LoginScreenComponent = ComponentType<LoginScreenProps>
+
+/**
+ * A way to surface a `begin`/`logout` outcome that has no inline screen to render it on.
+ *
+ * A header "Log in"/"Log out" control (`useLogin`/`useLogout`) fires the facade and forgets the
+ * result — it renders nothing of its own, unlike the sign-in screen, which already shows
+ * `loginAttemptError` inline. Registering one is how a UI package (`web-panel`, `mui-panel`) gives
+ * that control a way to speak — e.g. a toast when {@link LoginOutcome.Blocked} fires. Unregistered,
+ * it is silence, which is what a non-DOM host and a screen-mounted flow both already have.
+ */
+export interface LoginNotifier { (outcome: LoginOutcome, env: LoginEnv): void }
+
 export interface LoginService extends LazyService {
   registerPlugin: (plugin: LoginPlugin) => void
   /** Select the active plugin for the given (or default) environment. */
   plugin: (env?: LoginEnv) => LoginPlugin
   /** The environment the cascade is currently selecting on. */
   env: () => LoginEnv
+  /** Something that must hold before any flow starts. Checked synchronously, in `begin`. */
+  registerPrecondition: (precondition: LoginPrecondition) => void
+  /** A source of offerable sign-in methods, scoped to this context. */
+  registerMethodSource: (source: LoginMethodSource) => void
+  methods: (ctx: LoginMethodContext) => LoginMethod[]
+  /**
+   * The screen a dispatcher renders when it cannot proceed.
+   *
+   * A slot rather than an import, because a relying party (`web-oidc-rp`) must never depend on a
+   * UI family (`web-panel` / `mui-panel`) — that edge would force every relying party to pick one.
+   */
+  registerScreen: (screen: LoginScreenComponent) => void
+  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.
@@ -110,8 +262,72 @@ export interface LoginService extends LazyService {
   begin: (request: LoginRequest) => Promise<LoginOutcome>
   authorize: (url: string) => Promise<LoginOutcome>
   complete: (token: string) => Promise<LoginOutcome>
+  resume: (token: string) => Promise<LoginOutcome>
+  logout: (request: LogoutRequest) => Promise<LoginOutcome>
+  logoutComplete: () => Promise<LoginOutcome>
   /** Adopt an issued bearer token as this context's authentication. */
   adopt: (token: string) => Promise<void>
+  /** Drop this document's authentication. The single de-adoption path. */
+  revoke: () => Promise<void>
+}
+
+/**
+ * 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>
+
+/**
+ * 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`.
+ */
+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>
+  /**
+   * This step is where the Terms confirmation lives instead of on the sign-in screen.
+   *
+   * `termsDeferred(ctx)` (`./terms.js`) is true only while a step with this flag is both
+   * registered AND bound (`ctx.hasEntrypoint(step.entrypoint)`) — an app that registers the step
+   * but never binds its screen keeps the sign-in checkbox, fail-closed.
+   */
+  confirmsTerms?: boolean
+  /**
+   * A `pending` that throws or times out counts as PENDING rather than "not pending".
+   *
+   * The default (`undefined`/`false`) keeps every existing step fail-open, exactly as before —
+   * this flag is for a step whose whole point is to gate the landing on something the person must
+   * do (Terms confirmation), where a broken read must show the step rather than let it through.
+   */
+  required?: boolean
+}
+
+/**
+ * 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>
 }
 
 export interface LoginServiceAppend {