@owlmeans/client-auth 0.1.18-rc.2 → 0.1.18-rc.21

package/src/login/resume.ts

@@ -0,0 +1,56 @@
+import { LoginOutcome } from './types.js'
+
+/**
+ * The message key a FINISHED sign-in attempt should show, or null when it actually went somewhere.
+ *
+ * A dispatcher may treat `Passed` as "carry on with the ordinary continuation", because it has one.
+ * A screen does not: the user clicked, the document did not move, and nothing rendered — which is
+ * indistinguishable from a broken button, and is exactly how a null authorization URL used to
+ * present itself. Every outcome that leaves the user looking at the same screen therefore has to
+ * say something.
+ */
+export const loginAttemptError = (outcome: LoginOutcome | null): string | null => {
+  switch (outcome) {
+    case LoginOutcome.Gesture:
+      // The window never opened. That is the popup blocker, and it has its own copy.
+      return 'login.error.blocked'
+    case LoginOutcome.Failed:
+    case LoginOutcome.Passed:
+      return 'login.error.failed'
+    default:
+      // Handled, Redirected and Orphaned all did something; Orphaned reports itself elsewhere.
+      return null
+  }
+}
+
+/** What a dispatcher does once `login().resume(...)` has answered. */
+export enum ResumeAction {
+  /** The plugin took it over — the browser is leaving, or the window is closing. */
+  Stop = 'stop',
+  /** Render the outcome to the user; there is nothing further to do automatically. */
+  Render = 'render',
+  /** Ordinary tab: keep the session and carry on to the application. */
+  Navigate = 'navigate',
+}
+
+/**
+ * The one reading of a `resume` outcome, shared by every dispatcher.
+ *
+ * Exported as a pure function because three dispatchers — `web-client`, `web-oidc-rp` and
+ * `mui-oidc-rp` — have to agree on it, and the last time they each held their own copy of a
+ * decision they drifted, which is how a popup came to render the application inside itself in two
+ * packages at once. It is also the whole rule, so it is testable without a DOM.
+ */
+export const resumeAction = (outcome: LoginOutcome): ResumeAction => {
+  switch (outcome) {
+    case LoginOutcome.Handled:
+    case LoginOutcome.Redirected:
+      return ResumeAction.Stop
+    case LoginOutcome.Orphaned:
+    case LoginOutcome.Failed:
+    case LoginOutcome.Gesture:
+      return ResumeAction.Render
+    default:
+      return ResumeAction.Navigate
+  }
+}

package/src/login/screen.tsx

@@ -0,0 +1,136 @@
+import { useCallback, useState } from 'react'
+import type { CSSProperties, FC } 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 { resolveCredit } from './credit.js'
+
+/**
+ * The page the card sits in.
+ *
+ * It carries its own viewport height because this screen is rendered straight out of the
+ * dispatcher, into whatever the application happens to have around it — which is usually nothing
+ * with a height, so a percentage minimum would resolve to zero and leave the card at the top.
+ */
+const page: CSSProperties = {
+  display: 'flex', alignItems: 'center', justifyContent: 'center',
+  minHeight: '100dvh', padding: '1rem',
+  fontFamily: 'system-ui, sans-serif', lineHeight: 1.5,
+}
+
+// Centred throughout, so the plain screen and the styled one read the same way.
+const box: CSSProperties = {
+  width: '100%', maxWidth: '24rem', padding: '1.5rem', textAlign: 'center',
+}
+
+const button = (emphasis?: string): CSSProperties => ({
+  display: 'block', width: '100%', marginTop: '.5rem', padding: '.625rem 1rem',
+  fontSize: '1rem', cursor: 'pointer', borderRadius: '.375rem',
+  border: '1px solid currentColor',
+  ...(emphasis === 'primary' ? { fontWeight: 600 } : {}),
+})
+
+/**
+ * The sign-in screen every application gets, whether or not it registered a styled one.
+ *
+ * It exists because a relying party must render SOMETHING rather than start a flow on its own, and
+ * a relying party may not depend on a UI family. So this is deliberately plain: raw elements and
+ * inline styles, no Tailwind class that a consumer's stylesheet would have to scan for, no shadcn
+ * primitive a consumer would have to vendor. An application that registers a real screen through
+ * `login().registerScreen(...)` never sees it.
+ *
+ * Because it is the floor rather than the design, it still has to be correct: it offers the same
+ * methods, enforces the same terms confirmation, centres the same way, and renders the same
+ * credit line.
+ */
+export const FallbackLoginScreen: FC<LoginScreenProps> = props => {
+  const context = useContext() as unknown as LoginContext
+  const t = props.translate ?? ((_key: string, defaultValue: string) => defaultValue)
+  const cfg = props.config ?? (context.cfg as CommonConfig).security?.auth?.login
+  const brand = (context.cfg as CommonConfig).brand
+
+  const login = context.service<LoginService>(LOGIN_SERVICE)
+  const env = login.env()
+  const resolved = resolveTerms(props.terms ?? cfg?.terms)
+  const credit = resolveCredit(cfg?.credit, brand, context.cfg.service)
+
+  const [accepted, setAccepted] = useState(() => termsAccepted(resolved))
+  const [attempted, setAttempted] = useState(false)
+
+  const all = login.methods({ context, env })
+  const methods = typeof props.methods === 'function'
+    ? props.methods(all)
+    : props.methods ?? all
+  const primary = primaryLoginMethod(methods)
+
+  const blocked = resolved != null && resolved.required && !accepted
+
+  const select = useCallback((method: LoginMethod) => {
+    if (blocked) {
+      setAttempted(true)
+      return
+    }
+    void method.start({ context, env })
+  }, [blocked, context, env])
+
+  const onAccept = useCallback((value: boolean) => {
+    setAccepted(value)
+    setAttempted(false)
+    acceptTerms(resolved, value)
+  }, [resolved])
+
+  return <div data-login-screen style={page}><div style={box}>
+    <h1 style={{ fontSize: '1.25rem', marginBottom: '.25rem' }}>
+      {props.title ?? t('login.title', 'Sign in')}
+    </h1>
+    <p style={{ opacity: .75, marginTop: 0 }}>
+      {props.subtitle ?? t('login.subtitle', 'Choose how you would like to continue.')}
+    </p>
+
+    {methods.length < 1
+      ? <p role="status">{t('login.empty', 'No sign-in method is configured for this application.')}</p>
+      : methods.map(method => <button
+        key={method.id} type="button" data-login-method={method.id}
+        // `aria-disabled`, never `disabled`: a disabled button swallows the click, so a user who
+        // has not confirmed the terms would press it and be told nothing at all.
+        aria-disabled={blocked} data-blocked={blocked ? 'true' : undefined}
+        style={{ ...button(method.emphasis), opacity: blocked ? .6 : 1 }}
+        autoFocus={method.id === primary?.id}
+        onClick={() => select(method)}
+      >
+        {method.label ?? t(`login.method.${method.i18nKey ?? method.id}`, method.id)}
+      </button>)}
+
+    {resolved != null && <p style={{ marginTop: '1rem', fontSize: '.875rem' }}>
+      <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.')}
+      </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.')}
+    </p>}
+
+    {props.footer ?? <p style={{ marginTop: '2rem', fontSize: '.75rem', opacity: .7 }}>
+      {credit.poweredBy && <span>{t('login.credit.powered', 'Powered by OwlMeans')}</span>}
+      {credit.poweredBy && credit.line != null && ' · '}
+      {credit.line}
+    </p>}
+  </div></div>
+}

package/src/login/service.ts

@@ -0,0 +1,181 @@
+import { createLazyService } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { CommonConfig } from '@owlmeans/config'
+import { DEFAULT_ALIAS } from './consts.js'
+import { defaultLoginEnv } from './env.js'
+import { adoptToken, revokeToken } from './adopt.js'
+import { resolveLoginMethods } from './methods.js'
+import { LoginOutcome } from './types.js'
+import type {
+  LoginContext, LoginMethodSource, LoginPlugin, LoginPrecondition, LoginScreenComponent,
+  LoginService, LoginServiceAppend
+} from './types.js'
+
+/**
+ * Login service = plugin host. It holds a registry of login plugins and, on every facade call,
+ * resolves the active plugin by cascade (priority desc, first whose `match(env)` is truthy) and
+ * delegates to it.
+ *
+ * The facade methods stay ordinary writable properties (never getters) so that non-plugin
+ * implementations — e.g. a native login service — can keep overriding them directly.
+ *
+ * It is a LAZY service on purpose. The host carries no async setup, and plugin packages must be
+ * able to reach it from an app's `makeContext` — i.e. while the context is still in the Loading
+ * stage. `context.service()` throws for an uninitialized non-lazy service, which would make
+ * `ensureLoginService` fail exactly where apps are told to call it.
+ *
+ * `begin` and `logout` are deliberately NOT `async`. An async facade method defers the plugin's
+ * body past a microtask boundary, and a `window.open` that lands after the user gesture has
+ * finished being handled is eaten by the popup blocker. The same rule binds every plugin's own
+ * `begin` and `logout`, and it is why a precondition must be synchronous too.
+ */
+export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService => {
+  const plugins: LoginPlugin[] = []
+  const preconditions: LoginPrecondition[] = []
+  const methodSources: LoginMethodSource[] = []
+  let screen: LoginScreenComponent | null = null
+
+  const ctx = (): LoginContext => service.ctx as LoginContext
+
+  const service: LoginService = createLazyService<LoginService>(alias, {
+    registerPlugin: (plugin: LoginPlugin) => {
+      const existing = plugins.findIndex(candidate => candidate.alias === plugin.alias)
+      if (existing >= 0) {
+        plugins.splice(existing, 1)
+      }
+      plugins.push(plugin)
+      plugins.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+    },
+
+    registerPrecondition: (precondition: LoginPrecondition) => {
+      const existing = preconditions.findIndex(candidate => candidate.alias === precondition.alias)
+      if (existing >= 0) {
+        preconditions.splice(existing, 1)
+      }
+      preconditions.push(precondition)
+      preconditions.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+    },
+
+    registerMethodSource: (source: LoginMethodSource) => {
+      const existing = methodSources.findIndex(candidate => candidate.alias === source.alias)
+      if (existing >= 0) {
+        methodSources.splice(existing, 1)
+      }
+      methodSources.push(source)
+    },
+
+    methods: methodCtx => resolveLoginMethods(
+      methodCtx,
+      (methodCtx.context.cfg as CommonConfig).security?.auth?.login,
+      methodSources
+    ),
+
+    registerScreen: value => { screen = value },
+
+    screen: () => screen,
+
+    plugin: env => {
+      const environment = env ?? defaultLoginEnv()
+      const plugin = plugins.find(
+        candidate => candidate.match?.(environment, service.ctx as LoginContext | undefined) ?? true
+      )
+      if (plugin == null) {
+        throw new Error('login: no plugin matches the current environment')
+      }
+      return plugin
+    },
+
+    env: () => defaultLoginEnv(),
+
+    enter: () => {
+      const env = defaultLoginEnv()
+      service.plugin(env).enter?.(ctx(), env)
+    },
+
+    begin: request => {
+      const env = defaultLoginEnv()
+      // Synchronously, before anything can open a window: a precondition that refuses leaves the
+      // user exactly where `Gesture` describes — unable to proceed until they act again.
+      for (const precondition of preconditions) {
+        if (!precondition.check(ctx(), request, env)) {
+          return Promise.resolve(LoginOutcome.Gesture)
+        }
+      }
+
+      return service.plugin(env).begin(ctx(), request, env)
+    },
+
+    authorize: async url => {
+      const env = defaultLoginEnv()
+
+      return await service.plugin(env).authorize(ctx(), url, env)
+    },
+
+    complete: async token => {
+      const env = defaultLoginEnv()
+
+      return await service.plugin(env).complete(ctx(), token, env)
+    },
+
+    resume: async token => {
+      const env = defaultLoginEnv()
+      // Absent means "keep it and carry on" — which is what an ordinary tab has always done, and
+      // is why the redirect plugin implements nothing here.
+      return await service.plugin(env).resume?.(ctx(), token, env) ?? LoginOutcome.Passed
+    },
+
+    logout: request => {
+      const env = defaultLoginEnv()
+      const plugin = service.plugin(env)
+      if (plugin.logout == null) {
+        // A plugin with no logout mechanic still has to end the session it started.
+        return revokeToken(ctx()).then(async () => {
+          await request.navigate?.()
+
+          return LoginOutcome.Passed
+        })
+      }
+
+      return plugin.logout(ctx(), request, env)
+    },
+
+    logoutComplete: async () => {
+      const env = defaultLoginEnv()
+
+      return await service.plugin(env).logoutComplete?.(ctx(), env) ?? LoginOutcome.Passed
+    },
+
+    adopt: async token => { await adoptToken(ctx(), token) },
+
+    revoke: async () => { await revokeToken(ctx()) },
+  })
+
+  return service
+}
+
+/**
+ * Idempotently obtain the login service on a context, registering an empty host if none exists
+ * yet. Plugin packages call this before `registerPlugin`.
+ */
+export const ensureLoginService = (ctx: BasicContext<any>): LoginService => {
+  if (ctx.hasService(DEFAULT_ALIAS)) {
+    return ctx.service<LoginService>(DEFAULT_ALIAS)
+  }
+  const service = makeLoginService()
+  ctx.registerService(service)
+
+  return service
+}
+
+/** Register the host and expose it as `context.login()`. */
+export const appendLogin = <C extends BasicConfig, T extends BasicContext<C>>(
+  ctx: T
+): T & LoginServiceAppend => {
+  ensureLoginService(ctx)
+  const contextual = ctx as T & LoginServiceAppend
+  contextual.login = () => ctx.service<LoginService>(DEFAULT_ALIAS)
+
+  return contextual
+}
+
+export { LoginOutcome }

package/src/login/surrogate.ts

@@ -0,0 +1,45 @@
+import { DISPATCHER_SURROGATE } from '@owlmeans/auth'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { LOGIN_INTENT_QUERY, LOGIN_METHOD_QUERY, LOGIN_NEXT_QUERY } from './consts.js'
+import { LoginIntent } from './types.js'
+import type { LoginContext } from './types.js'
+
+export interface SurrogateTarget {
+  intent: LoginIntent
+  /** The address the surrogate should actually run, once it is one window up. */
+  next?: string
+  /** The method the user already chose in the opener. */
+  method?: string
+}
+
+/**
+ * Where a surrogate window opens.
+ *
+ * Returns `null` when the application's entrypoint list predates the surrogate route — an app
+ * built against an older `@owlmeans/auth-common` has no such entrypoint, and the caller then falls
+ * back to opening the dispatcher directly, which is exactly what it used to do. That fallback is
+ * the whole compatibility story for already-deployed applications, so it must never be removed in
+ * favour of throwing.
+ */
+export const surrogatePath = (ctx: LoginContext, target: SurrogateTarget): string | null => {
+  if (!ctx.hasEntrypoint(DISPATCHER_SURROGATE)) {
+    return null
+  }
+  let path: string
+  try {
+    path = ctx.entrypoint<ClientEntrypoint>(DISPATCHER_SURROGATE).path()
+  } catch {
+    return null
+  }
+
+  const query = new URLSearchParams()
+  query.set(LOGIN_INTENT_QUERY, target.intent)
+  if (target.next != null && target.next !== '') {
+    query.set(LOGIN_NEXT_QUERY, target.next)
+  }
+  if (target.method != null && target.method !== '') {
+    query.set(LOGIN_METHOD_QUERY, target.method)
+  }
+
+  return `${path}?${query.toString()}`
+}

package/src/login/types.ts

@@ -0,0 +1,258 @@
+import type { ComponentType, CSSProperties, ReactNode } from 'react'
+import type { LazyService, BasicContext } from '@owlmeans/context'
+import type { LoginMethodEmphasis, LoginScreenConfig, LoginTermsConfig } from '@owlmeans/config'
+
+/**
+ * The context a login plugin is handed.
+ *
+ * Deliberately `BasicContext<any>`, matching `RouterService`: a plugin only ever reaches services
+ * by alias, and pinning the config parameter would make every concrete app config — each of which
+ * adds its own required fields — fail to satisfy it, since `makeContext` is invariant in it.
+ */
+export type LoginContext = BasicContext<any>
+
+/**
+ * Environment descriptor the cascade selects a login plugin on.
+ *
+ * This is the single source of environment truth — do NOT bake `window.self !== window.top` or a
+ * `sessionStorage` probe into a plugin's `match`. A native host will supply its own descriptor
+ * (`hasWindow: false`) so an in-app-browser plugin wins there without any DOM check.
+ */
+export interface LoginEnv {
+  /** A DOM is present at all (false under SSR, native, and unit tests). */
+  hasWindow: boolean
+  /** This document is embedded in a frame. A cross-origin `top` read throws — that throw counts. */
+  embedded: boolean
+  /** This document IS the surrogate login window; survives the cross-origin round trip. */
+  surrogate: boolean
+  /** The window that opened this one is still reachable (COOP severs it permanently). */
+  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 it. */
+  Orphaned = 'orphaned',
+  /** The attempt ended with no token (blocked window, user closed it, provider refused). */
+  Failed = 'failed',
+}
+
+/** Why a surrogate window was opened. */
+export enum LoginIntent {
+  Login = 'login',
+  Logout = 'logout',
+}
+
+export interface LoginRequest {
+  /** Where the login flow starts — a resolved dispatcher path, or the current address. */
+  url: string
+  /**
+   * The ordinary in-app continuation, supplied by the caller because only a component may call
+   * `useNavigate`. A plugin that decides not to take the flow over calls this; without it the
+   * fallback is a full page load of {@link url}.
+   */
+  navigate?: () => void | Promise<void>
+  /** Entrypoint alias to return to after login. */
+  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.
+ *
+ * Not to be confused with `AuthenticationPlugin` (./manager/plugins), which answers *how* a user
+ * proves their identity. This one answers *in which browsing context the flow can complete*: a
+ * redirect works in an ordinary tab and cannot work inside a frame whose provider refuses to be
+ * embedded, and that difference is a property of the environment, not of the credential.
+ */
+export interface LoginPlugin {
+  alias: string
+  /** Higher wins among matching plugins. Defaults to 0. */
+  priority?: number
+  /** Free-form tag, e.g. 'redirect' | 'surrogate' | 'native'. */
+  mode?: string
+  /** Selector; `undefined` means "always applicable". */
+  match?: (env: LoginEnv, ctx?: LoginContext) => boolean
+
+  /**
+   * Record, while it is still knowable, whatever the later stages need about this document.
+   *
+   * Called synchronously as the FIRST statement of the dispatcher's effect: everything after it
+   * can navigate away, and some of the evidence (notably `window.name`) is cleared by the browser
+   * the moment a top-level context goes cross-origin.
+   */
+  enter?: (ctx: LoginContext, env: LoginEnv) => void
+
+  /**
+   * Start login from a user gesture.
+   *
+   * MUST open any window synchronously — the popup blocker only yields while the gesture is still
+   * being handled. Implement as a NON-async function returning a promise.
+   */
+  begin: (ctx: LoginContext, request: LoginRequest, env: LoginEnv) => Promise<LoginOutcome>
+
+  /** Send the browser to the identity provider's authorization URL. */
+  authorize: (ctx: LoginContext, url: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /** 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
+  /** 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>
+
+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
+  // 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.
+  enter: () => void
+  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>
+}
+
+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
+npm install @owlmeans/client-auth@^0.1.18-rc.19
 ```
 
 ## API Reference