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

package/src/login/pump.ts

@@ -0,0 +1,53 @@
+import { LOGIN_WATCH_INTERVAL, LoginOutcome } from '@owlmeans/client-auth/login'
+
+/**
+ * Wait on a surrogate window until it says something, or goes away.
+ *
+ * Extracted so login and logout share one implementation rather than two that agree until one of
+ * them is changed. Every guard here was a real failure at some point:
+ *
+ * - the **origin pin** is not decoration — the message carries a bearer token, and a listener that
+ *   accepted any origin would take one from any page that could reach this window;
+ * - the **`settled` latch** stops a second message, or a close racing a message, resolving twice;
+ * - the **`closed` poll** is the only exit when the user simply closes the window, because a window
+ *   the user closes announces nothing at all;
+ * - the listener and the interval are removed on every path, including the ones that resolve.
+ */
+export const awaitSurrogate = async (
+  surrogate: Window,
+  messageType: string,
+  onMessage: (data: { type?: string, token?: string, ok?: boolean }) => Promise<LoginOutcome>
+): Promise<LoginOutcome> => await new Promise<LoginOutcome>(resolve => {
+  let settled = false
+  let watch: ReturnType<typeof setInterval> | undefined
+
+  const finish = (result: LoginOutcome): void => {
+    if (settled) {
+      return
+    }
+    settled = true
+    window.removeEventListener('message', handler)
+    if (watch != null) {
+      clearInterval(watch)
+    }
+    resolve(result)
+  }
+
+  function handler(event: MessageEvent): void {
+    if (event.origin !== window.location.origin) {
+      return
+    }
+    const data = event.data as { type?: string, token?: string, ok?: boolean } | null
+    if (data?.type !== messageType) {
+      return
+    }
+    void onMessage(data).then(finish).catch(() => finish(LoginOutcome.Failed))
+  }
+
+  window.addEventListener('message', handler)
+  watch = setInterval(() => {
+    if (surrogate.closed) {
+      finish(LoginOutcome.Failed)
+    }
+  }, LOGIN_WATCH_INTERVAL)
+})

package/src/login/redirect.ts

@@ -1,5 +1,5 @@
-import { LoginOutcome } from '@owlmeans/client-auth/login'
-import type { LoginPlugin } from '@owlmeans/client-auth/login'
+import { LoginOutcome, loginTokenOf } from '@owlmeans/client-auth/login'
+import type { LoginContext, LoginPlugin } from '@owlmeans/client-auth/login'
 import { REDIRECT_LOGIN } from './consts.js'
 
 /**
@@ -35,4 +35,25 @@ export const makeRedirectLoginPlugin = (): LoginPlugin => ({
 
   // Nothing to hand anywhere — the token was issued in the document that will use it.
   complete: async () => LoginOutcome.Passed,
+
+  // `resume` is deliberately NOT implemented. The host defaults to `Passed`, which is "keep the
+  // session you already have and carry on" — byte for byte what an ordinary tab has always done.
+  // Implementing it here would be the one way to regress every unframed application.
+
+  logout: (ctx, request) => loginTokenOf(ctx as LoginContext).revokeToken().then(async () => {
+    if (request.navigate != null) {
+      await request.navigate()
+
+      return LoginOutcome.Handled
+    }
+    // A reload rather than a client-side navigation: `useOwlAuth` and its kin read through
+    // cached values, so the honest way to make a whole application forget a session is to
+    // rebuild it. This is what `useLogout` did inline before the mechanic became a plugin.
+    window.location.reload()
+
+    return LoginOutcome.Handled
+  }),
+
+  // Nothing to tell anyone — the session was cleared in the document that owned it.
+  logoutComplete: async () => LoginOutcome.Passed,
 })

package/src/login/screen.tsx

@@ -0,0 +1,141 @@
+import { useCallback, useEffect, useState, type FC } from 'react'
+import { useContext } from '@owlmeans/client'
+import { useI18nLib } from '@owlmeans/client-i18n'
+import { LoginIntent, LoginOutcome, LOGIN_INTENT_QUERY, LOGIN_METHOD_QUERY, LOGIN_NEXT_QUERY, type LoginService } from '@owlmeans/client-auth/login'
+import { USER_ID } from '@owlmeans/client-auth'
+import type { AppContext } from '../types.js'
+import { LoginSurrogateView } from './view.js'
+import { SurrogateStage } from './consts.js'
+import { logger } from '@owlmeans/log'
+import { SurrogateLoginStep } from './consts.js'
+
+const log = logger('web-client:login')
+/**
+ * A sign-in request never reuses the session this window happens to hold.
+ *
+ * The opener asks for a sign-in only when it has no session its server accepts — and the window it
+ * opens does not share its storage: an embedded application's storage is partitioned by the top
+ * level site, the popup's is first-party. So the popup can hold a session the server has already
+ * REFUSED (its record gone after a restart, revoked, fenced). Handing that back closes the popup
+ * at once — a blink — and the opener fails its next request exactly as before, forever, because
+ * nothing in the opener can reach the popup's storage to clear it. A fresh round trip costs only
+ * redirects while the provider still has a session, and always yields a session the server holds.
+ *
+ * Only without a dispatcher address is the stored session handed back as it is: there is nothing
+ * to authenticate through, and the opener's own 401 handling drops it if it is refused.
+ */
+export const surrogateLoginStep = (token: string | null | undefined, next: string | null): SurrogateLoginStep => {
+  const stored = token != null && token !== ''
+  if (!stored) {
+    return SurrogateLoginStep.Authenticate
+  }
+
+  return next != null && next !== '' ? SurrogateLoginStep.Forget : SurrogateLoginStep.Resume
+}
+
+export const SurrogateScreen: FC = () => {
+  const context = useContext() as unknown as AppContext
+  const [query] = context.router().useSearchParams()
+  const t = useI18nLib('auth')
+
+  const intent = query.get(LOGIN_INTENT_QUERY) === LoginIntent.Logout
+    ? LoginIntent.Logout
+    : LoginIntent.Login
+
+  const [stage, setStage] = useState<SurrogateStage>(SurrogateStage.Working)
+  const [error, setError] = useState<string | undefined>()
+
+  const onAction = useCallback(() => {
+    if (stage === SurrogateStage.Standalone) {
+      window.location.href = '/'
+      return
+    }
+    if (stage === SurrogateStage.Gesture) {
+      const next = query.get(LOGIN_NEXT_QUERY)
+      void context.login().begin({ url: next ?? window.location.href })
+      return
+    }
+    window.close()
+  }, [context, stage, query])
+
+  useEffect(() => {
+    const login = context.service<LoginService>('login-service')
+    // First statement, unconditionally: `markSurrogate` reads `window.name`, and the browser
+    // clears that the moment this window's top-level context goes cross-origin. Recording it
+    // later means recording nothing.
+    login.enter()
+
+    const env = login.env()
+    if (!env.surrogate) {
+      // Somebody opened this address directly, or the window lost its marker. Never navigate on
+      // its behalf — offer a link and stop.
+      setStage(env.embedded ? SurrogateStage.Gesture : SurrogateStage.Standalone)
+      return
+    }
+
+    const run = async (): Promise<void> => {
+      const token = await context.auth().authenticated()
+
+      if (intent === LoginIntent.Logout) {
+        // Revoked FIRST, before anything can be awaited on a channel that may never answer: a
+        // window the user closes half a second later must still have ended the session it opened
+        // to end.
+        await login.revoke()
+        const outcome = await login.logoutComplete()
+        setStage(
+          outcome === LoginOutcome.Handled ? SurrogateStage.Handing
+            : outcome === LoginOutcome.Orphaned ? SurrogateStage.Orphaned
+              : SurrogateStage.Failed
+        )
+        return
+      }
+
+      const next = query.get(LOGIN_NEXT_QUERY)
+      const step = surrogateLoginStep(token, next)
+
+      if (step === SurrogateLoginStep.Forget) {
+        // Dropped from this window's storage only — the web auth service's own clearing path
+        // navigates to the dispatcher, and `next` below is exactly where this window goes anyway.
+        const auth = context.auth()
+        await auth.store().delete(USER_ID)
+        auth.token = undefined
+        auth.auth = undefined
+      }
+
+      if (step === SurrogateLoginStep.Resume && token != null) {
+        // Signed in here and nowhere to authenticate afresh: hand what there is to the opener.
+        const outcome = await login.resume(token)
+        setStage(
+          outcome === LoginOutcome.Handled ? SurrogateStage.Handing
+            : outcome === LoginOutcome.Orphaned ? SurrogateStage.Orphaned
+              : SurrogateStage.Failed
+        )
+        return
+      }
+
+      // The dispatcher owns the authorization round trip, and the provider's callback lands there
+      // rather than on this route. The method the user already chose travels with it, so the
+      // dispatcher does not ask a second time in a window with no one to ask.
+      if (next == null || next === '') {
+        setStage(SurrogateStage.Gesture)
+        return
+      }
+      const method = query.get(LOGIN_METHOD_QUERY)
+      const target = method != null && method !== ''
+        ? `${next}${next.includes('?') ? '&' : '?'}${LOGIN_METHOD_QUERY}=${encodeURIComponent(method)}`
+        : next
+      window.location.href = target
+    }
+
+    void run().catch((e: Error) => {
+      log.error('Surrogate login failed', e)
+      setError(e.message)
+      setStage(SurrogateStage.Failed)
+    })
+  }, [context, intent])
+
+  return <LoginSurrogateView
+    stage={stage} intent={intent} onAction={onAction} error={error}
+    translate={(key, defaultValue) => t(key, { defaultValue })}
+  />
+}

package/src/login/surrogate.ts

@@ -1,9 +1,34 @@
-import {
-  adoptToken, clearSurrogate, markSurrogate, LoginOutcome,
-  LOGIN_SURROGATE_FEATURES, LOGIN_SURROGATE_NAME, LOGIN_TOKEN_MESSAGE, LOGIN_WATCH_INTERVAL,
-} from '@owlmeans/client-auth/login'
-import type { LoginContext, LoginPlugin } from '@owlmeans/client-auth/login'
+import { surrogatePath, LoginIntent, LoginOutcome, LOGIN_LOGOUT_MESSAGE, LOGIN_SURROGATE_HEIGHT, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_WIDTH, LOGIN_TOKEN_MESSAGE, loginEnvHelper, loginTokenOf } from '@owlmeans/client-auth/login'
+import type { LoginContext, LoginEnv, LoginPlugin } from '@owlmeans/client-auth/login'
 import { SURROGATE_LOGIN, SURROGATE_LOGIN_PRIORITY } from './consts.js'
+import { awaitSurrogate } from './pump.js'
+
+/**
+ * `window.open` features that size and CENTER the surrogate on the screen the browser window
+ * currently occupies.
+ *
+ * Computed fresh per call, never a constant: centering depends on where the browser window sits
+ * NOW, which can change between one login attempt and the next. `screenLeft`/`screenTop` and
+ * `outerWidth`/`outerHeight` describe the browser's own chrome rather than this document's
+ * viewport — and, unlike `innerWidth` or anything reached through `window.top`, they stay readable
+ * from a cross-origin iframe. That matters here specifically: a generated app's preview runs
+ * framed on a different origin than the manager that embeds it, so `env.embedded` is exactly the
+ * case where `window.top.innerWidth` would throw, and reading this document's own `innerWidth`
+ * instead would center the popup on the IFRAME's rectangle rather than on the actual window a
+ * person sees. Falling back to `window.screen` covers a window that reports no outer geometry at
+ * all (a headless test runner).
+ */
+export const centeredPopupFeatures = (width: number, height: number): string => {
+  const screenLeft = window.screenLeft ?? window.screenX ?? 0
+  const screenTop = window.screenTop ?? window.screenY ?? 0
+  const outerWidth = window.outerWidth || window.screen.width
+  const outerHeight = window.outerHeight || window.screen.height
+
+  const left = Math.round(screenLeft + Math.max(0, (outerWidth - width) / 2))
+  const top = Math.round(screenTop + Math.max(0, (outerHeight - height) / 2))
+
+  return `popup=yes,width=${width},height=${height},left=${left},top=${top}`
+}
 
 /**
  * Login for a document that cannot complete the flow where it is.
@@ -23,101 +48,160 @@ import { SURROGATE_LOGIN, SURROGATE_LOGIN_PRIORITY } from './consts.js'
  * top-level, so it authorizes by an ordinary redirect and differs only in what it does with the
  * token at the end.
  */
-export const makeSurrogateLoginPlugin = (): LoginPlugin => ({
-  alias: SURROGATE_LOGIN,
-  priority: SURROGATE_LOGIN_PRIORITY,
-  mode: 'surrogate',
-  match: env => env.hasWindow && (env.embedded || env.surrogate),
+export const makeSurrogateLoginPlugin = (): LoginPlugin => {
+  /**
+   * Give the token to whoever is entitled to it, and get out of the way.
+   *
+   * Shared by `complete` (a token was just issued here) and `resume` (one was already here),
+   * because what happens to it is the same in both cases and only the question differs.
+   */
+  const handBack = async (token: string, env: LoginEnv): Promise<LoginOutcome> => {
+    if (!env.surrogate) {
+      // This document started the flow and finished it in place — it already has what it needs.
+      return LoginOutcome.Passed
+    }
+    if (!env.hasOpener) {
+      // Authenticated with nowhere to send it. `Cross-Origin-Opener-Policy: same-origin` from the
+      // provider severs `window.opener` permanently, so this is not a timing problem to retry.
+      return LoginOutcome.Orphaned
+    }
 
-  enter: () => { markSurrogate() },
+    loginEnvHelper.clearSurrogate()
+    // Both windows are the same origin (the surrogate is this application's own login route), so
+    // the origin is pinned rather than passed as `*` — the message carries a bearer token.
+    window.opener.postMessage({ type: LOGIN_TOKEN_MESSAGE, token }, window.location.origin)
+    window.close()
 
-  begin: (ctx, request, env) => {
-    // Already one window up — nothing to open, just run the flow.
-    if (env.surrogate) {
-      window.location.href = request.url
+    return LoginOutcome.Handled
+  }
 
-      return Promise.resolve(LoginOutcome.Redirected)
-    }
+  const plugin: LoginPlugin = {
+    alias: SURROGATE_LOGIN,
+    priority: SURROGATE_LOGIN_PRIORITY,
+    mode: 'surrogate',
+    match: env => env.hasWindow && (env.embedded || env.surrogate),
 
-    // Opened FIRST and synchronously: `window.open` escapes the popup blocker only while the user
-    // gesture is still being handled, so nothing may be awaited before this line. That is why this
-    // function is not `async`.
-    const surrogate = window.open(request.url, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_FEATURES)
-    if (surrogate == null) {
-      return Promise.resolve(LoginOutcome.Failed)
-    }
+    enter: () => { loginEnvHelper.markSurrogate() },
 
-    return new Promise<LoginOutcome>(resolve => {
-      let settled = false
-      let watch: ReturnType<typeof setInterval> | undefined
+    begin: (ctx, request, env) => {
+      // Already one window up — nothing to open, just run the flow.
+      if (env.surrogate) {
+        window.location.href = request.url
 
-      const finish = (result: LoginOutcome): void => {
-        if (settled) {
-          return
-        }
-        settled = true
-        window.removeEventListener('message', onMessage)
-        if (watch != null) {
-          clearInterval(watch)
-        }
-        resolve(result)
+        return Promise.resolve(LoginOutcome.Redirected)
       }
 
-      function onMessage(event: MessageEvent): void {
-        if (event.origin !== window.location.origin) {
-          return
-        }
-        const data = event.data as { type?: string, token?: string } | null
-        if (data?.type !== LOGIN_TOKEN_MESSAGE || data.token == null || data.token === '') {
-          return
-        }
-        void adoptToken(ctx as LoginContext, data.token)
-          .then(() => finish(LoginOutcome.Handled))
-          .catch(() => finish(LoginOutcome.Failed))
+      // Opened FIRST and synchronously: `window.open` escapes the popup blocker only while the
+      // user gesture is still being handled, so nothing may be awaited before this line. That is
+      // why this function is not `async`.
+      //
+      // The window opens on the surrogate route rather than on the dispatcher, so its very first
+      // paint is a bare "signing you in" panel instead of the application with its navigation. The
+      // dispatcher address travels as `next`, because the provider's callback still lands there and
+      // whatever flow parameters the caller's URL carried must survive the hop.
+      const path = surrogatePath(ctx as LoginContext, {
+        intent: LoginIntent.Login, next: request.url,
+      })
+      const surrogate = window.open(
+        path ?? request.url, LOGIN_SURROGATE_NAME,
+        centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT)
+      )
+      if (surrogate == null) {
+        // Distinct from `Failed` below: nothing ever opened, so there is nothing left to wait on.
+        return Promise.resolve(LoginOutcome.Blocked)
       }
 
-      window.addEventListener('message', onMessage)
-      // A window the user simply closes announces nothing, so the only way to stop waiting on it
-      // is to watch for it going away.
-      watch = setInterval(() => {
-        if (surrogate.closed) {
-          finish(LoginOutcome.Failed)
+      return awaitSurrogate(surrogate, LOGIN_TOKEN_MESSAGE, async data => {
+        if (data.token == null || data.token === '') {
+          return LoginOutcome.Failed
         }
-      }, LOGIN_WATCH_INTERVAL)
-    })
-  },
+        await loginTokenOf(ctx as LoginContext).adoptToken(data.token)
+        // Adopting the token is not the end of the flow — running the caller's continuation is,
+        // exactly as the redirect plugin does before it reports `Handled`. Without it the token
+        // lands in the auth service and nothing else happens: the framed app keeps rendering its
+        // signed-out tree, and the user watches the login window close over a preview that never
+        // changes. `Handled` promises the caller there is nothing left to do.
+        await request.navigate?.()
 
-  authorize: async (_ctx, url, env) => {
-    // The surrogate is top-level, so it redirects like any ordinary tab.
-    if (env.surrogate) {
-      window.location.href = url
+        return LoginOutcome.Handled
+      })
+    },
 
-      return LoginOutcome.Redirected
-    }
+    authorize: async (_ctx, url, env) => {
+      // The surrogate is top-level, so it redirects like any ordinary tab.
+      if (env.surrogate) {
+        window.location.href = url
 
-    // Framed, and not yet one window up. A redirect from here would land in the frame and be
-    // refused, and the window that would fix it cannot be opened without a user gesture — so the
-    // caller is told to render a control rather than to navigate.
-    return LoginOutcome.Gesture
-  },
+        return LoginOutcome.Redirected
+      }
 
-  complete: async (_ctx, token, env) => {
-    if (!env.surrogate) {
-      // This document started the flow and finished it in place — it already has what it needs.
-      return LoginOutcome.Passed
-    }
-    if (!env.hasOpener) {
-      // Authenticated with nowhere to send it. `Cross-Origin-Opener-Policy: same-origin` from the
-      // provider severs `window.opener` permanently, so this is not a timing problem to retry.
-      return LoginOutcome.Orphaned
-    }
+      // Framed, and not yet one window up. A redirect from here would land in the frame and be
+      // refused, and the window that would fix it cannot be opened without a user gesture — so the
+      // caller is told to render a control rather than to navigate.
+      return LoginOutcome.Gesture
+    },
 
-    clearSurrogate()
-    // Both windows are the same origin (the surrogate is this application's own login route), so
-    // the origin is pinned rather than passed as `*` — the message carries a bearer token.
-    window.opener.postMessage({ type: LOGIN_TOKEN_MESSAGE, token }, window.location.origin)
-    window.close()
+    complete: async (_ctx, token, env) => await handBack(token, env),
 
-    return LoginOutcome.Handled
-  },
-})
+    // A session that was already here is worth exactly as much as one just issued — to the window
+    // that asked for it. Without this the surrogate would render the signed-in application to
+    // itself and the framed app would stay signed out, which is the whole reported defect.
+    resume: async (_ctx, token, env) => await handBack(token, env),
+
+    logout: (ctx, request, env) => {
+      // Already one window up — end the session here and tell the opener.
+      if (env.surrogate) {
+        return loginTokenOf(ctx as LoginContext).revokeToken()
+          .then(async () => await plugin.logoutComplete!(ctx, env))
+      }
+
+      const path = surrogatePath(ctx as LoginContext, { intent: LoginIntent.Logout })
+      // Opened first and synchronously, for the same reason `begin` does.
+      const surrogate = path != null
+        ? window.open(path, LOGIN_SURROGATE_NAME,
+          centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT))
+        : null
+
+      // The local session goes next, and UNCONDITIONALLY. A blocked window, a severed opener or a
+      // user who closes the popup must never leave THIS document signed in: a logout that only
+      // half happened is bad, and one that did not happen at all is worse.
+      const local = loginTokenOf(ctx as LoginContext).revokeToken()
+      if (surrogate == null) {
+        // `path == null` is an app whose entrypoint list predates the surrogate route — nothing a
+        // retry would do differently. A `window.open` the browser refused is the one case worth
+        // telling the user about, so only that one reports `Blocked`.
+        const outcome = path != null ? LoginOutcome.Blocked : LoginOutcome.Failed
+
+        return local.then(async () => {
+          await request.navigate?.()
+
+          return outcome
+        })
+      }
+
+      return local.then(async () => await awaitSurrogate(
+        surrogate, LOGIN_LOGOUT_MESSAGE, async () => {
+          await request.navigate?.()
+
+          return LoginOutcome.Handled
+        }
+      ))
+    },
+
+    logoutComplete: async (_ctx, env) => {
+      if (!env.surrogate) {
+        return LoginOutcome.Passed
+      }
+      if (!env.hasOpener) {
+        return LoginOutcome.Orphaned
+      }
+      loginEnvHelper.clearSurrogate()
+      window.opener.postMessage({ type: LOGIN_LOGOUT_MESSAGE, ok: true }, window.location.origin)
+      window.close()
+
+      return LoginOutcome.Handled
+    },
+  }
+
+  return plugin
+}

package/src/login/types.ts

@@ -0,0 +1,10 @@
+import { LoginIntent } from '@owlmeans/client-auth/login'
+import { SurrogateStage } from './consts.js'
+
+export interface SurrogateViewProps {
+  stage: SurrogateStage
+  intent: LoginIntent
+  onAction?: () => void
+  error?: string
+  translate?: (key: string, defaultValue: string) => string
+}

package/src/login/view.tsx

@@ -0,0 +1,22 @@
+import type { FC } from 'react'
+import { LoginIntent } from '@owlmeans/client-auth/login'
+import { action, box, COPY, LOGOUT_COPY } from './consts.local.js'
+import type { SurrogateViewProps } from './types.js'
+
+export const LoginSurrogateView: FC<SurrogateViewProps> = (
+  { stage, intent, onAction, error, translate }
+) => {
+  const t = translate ?? ((_key: string, defaultValue: string) => defaultValue)
+  const scope = intent === LoginIntent.Logout ? 'logout' : 'login'
+  const base = COPY[stage]
+  const copy = (intent === LoginIntent.Logout ? LOGOUT_COPY[stage] : undefined) ?? base
+
+  return <div style={box} data-surrogate-stage={stage} data-surrogate-intent={intent}>
+    <p>{t(`surrogate.${scope}.${copy.key}`, copy.en)}</p>
+    {error != null && error !== '' &&
+      <p style={{ color: '#b00', fontSize: '.875rem' }} role="alert">{error}</p>}
+    {base.action != null && onAction != null && <button type="button" style={action} onClick={onAction}>
+      {t(`surrogate.${scope}.${base.action[0]}`, base.action[1])}
+    </button>}
+  </div>
+}

package/src/main.tsx

@@ -9,9 +9,6 @@ export const render = (node: ReactNode, opts?: RenderOptions) => {
   const _callback = () => {
     const key = opts?.domId ?? DEFAULT_ROOT
     const root = document.getElementById(key)
-    if (opts?.debug) {
-      console.debug(`Render react app to ${key}`)
-    }
     if (root == null) {
       throw new Error(`Root element not found with id: ${key}`)
     }
@@ -22,8 +19,24 @@ export const render = (node: ReactNode, opts?: RenderOptions) => {
     }
   }
 
-  opts?.onReady ?? true ? window.addEventListener('DOMContentLoaded', _callback) : _callback()
+  // Wait for the DOM only while it is still loading: a caller that awaits something first
+  // (`await prepareI18n(cfg); render(...)`) can run after `DOMContentLoaded` has already fired,
+  // and a listener added then never runs — the app would never mount.
+  if ((opts?.onReady ?? true) && document.readyState === 'loading') {
+    window.addEventListener('DOMContentLoaded', _callback, { once: true })
+  } else {
+    _callback()
+  }
 }
 
-export const renderApp = <C extends AppConfig, T extends AppContext<C>>(context: T, opts?: RenderOptions) =>
-  render(<WebApp context={context} />, opts)
+/**
+ * Mount the application.
+ *
+ * `children` are rendered inside the context provider and BEFORE the router, which makes them the
+ * app's global overlay slot: a consent dialog, a toast surface, anything that must exist on every
+ * route and outlive navigation. A component mounted inside a route instead is torn down and
+ * rebuilt on every navigation, which for a dialog means it closes itself.
+ */
+export const renderApp = <C extends AppConfig, T extends AppContext<C>>(
+  context: T, opts?: RenderOptions, children?: ReactNode
+) => render(<WebApp context={context}>{children}</WebApp>, opts)

package/src/middleware.ts

@@ -1,28 +1,28 @@
-import type { Middleware } from '@owlmeans/context'
-import { MiddlewareType, MiddlewareStage, AppType } from '@owlmeans/context'
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { type Middleware, MiddlewareType, MiddlewareStage, AppType } from '@owlmeans/context'
 import { AuthUnknown } from '@owlmeans/auth'
 import { ResilientError } from '@owlmeans/error'
 import { DEFAULT_ALIAS } from '@owlmeans/client-auth'
 import { AuthService } from '@owlmeans/auth-common'
+import type { Perked } from './types.local.js'
 
 export const logoutMiddleware: Middleware = {
   type: MiddlewareType.Context,
   stage: MiddlewareStage.Loading,
   apply: async context => {
     context.entrypoints<Perked>().forEach(module => {
-      if (module.route.route.type === AppType.Backend && module.call != null) {
+      if (module.route.route.type === AppType.Backend && module.invoke != null) {
         const guards = module.getGuards()
         if (guards.length > 0) {
           if (module._auth_web_middleware_applied === true) {
             return
           }
           module._auth_web_middleware_applied = true
-          // const auth = context.service<GuardService>(service)
-          const call = module.call
-          module.call = async (req, res) => {
+          // Wrapping `invoke` covers `call` too: `call` reads `invoke` off the entrypoint at the
+          // moment it runs, so a rejected session is caught whichever verb the caller used.
+          const invoke = module.invoke
+          module.invoke = (async req => {
             try {
-              return await call(req, res)
+              return await invoke(req)
             } catch (e) {
               if (e instanceof Error) {
                 const err = ResilientError.ensure(e)
@@ -38,7 +38,7 @@ export const logoutMiddleware: Middleware = {
               }
               throw e
             }
-          }
+          }) as typeof module.invoke
 
         }
       }
@@ -46,6 +46,3 @@ export const logoutMiddleware: Middleware = {
   }
 }
 
-interface Perked extends ClientEntrypoint<unknown> {
-  _auth_web_middleware_applied?: boolean
-}

package/src/service.ts

@@ -16,7 +16,7 @@ export const makeAuthWebService = (alias: string = DEFAULT_ALIAS): AuthService =
     await update(token)
     if (token == null) {
       const module = service.assertCtx().entrypoint<ClientEntrypoint<string>>(DISPATCHER)
-      const [url] = await module.call()
+      const url = await module.url()
       document.location.href = url
     }
   }

package/src/types.local.ts

@@ -0,0 +1,5 @@
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+
+export interface Perked extends ClientEntrypoint<unknown> {
+  _auth_web_middleware_applied?: boolean
+}