@owlmeans/web-client 0.1.18-rc.2 → 0.1.18-rc.20

package/src/login/redirect.ts

@@ -0,0 +1,59 @@
+import { revokeToken, LoginOutcome } from '@owlmeans/client-auth/login'
+import type { LoginContext, LoginPlugin } from '@owlmeans/client-auth/login'
+import { REDIRECT_LOGIN } from './consts.js'
+
+/**
+ * The ordinary login flow: this document leaves for the identity provider and comes back.
+ *
+ * The default plugin, matching everything, so any environment that does not need special handling
+ * behaves exactly as it always did.
+ */
+export const makeRedirectLoginPlugin = (): LoginPlugin => ({
+  alias: REDIRECT_LOGIN,
+  priority: 0,
+  mode: 'redirect',
+  match: () => true,
+
+  begin: async (_ctx, request) => {
+    // Prefer the in-app continuation the caller handed over: a client-side navigation to the
+    // dispatcher keeps the app mounted, where a full page load would tear it down and rebuild it.
+    if (request.navigate != null) {
+      await request.navigate()
+
+      return LoginOutcome.Handled
+    }
+    window.location.href = request.url
+
+    return LoginOutcome.Redirected
+  },
+
+  authorize: async (_ctx, url) => {
+    window.location.href = url
+
+    return LoginOutcome.Redirected
+  },
+
+  // 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) => revokeToken(ctx as LoginContext).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,119 @@
+import { useCallback, useEffect, useState } from 'react'
+import 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,
+} from '@owlmeans/client-auth/login'
+import type { LoginService } from '@owlmeans/client-auth/login'
+import type { AppContext } from '../types.js'
+import { LoginSurrogateView, SurrogateStage } from './view.js'
+
+/**
+ * The login window an embedded application opens one level up.
+ *
+ * It is NOT wrapped in `DispatcherHOC`, and that is the point: the HOC's continuation navigates to
+ * `HOME` when it has nothing else to do, which is how a popup ended up rendering the whole
+ * application, with its navigation, inside itself. This screen has no continuation at all — it
+ * either hands something back and closes, or it says what it is waiting for.
+ *
+ * It also never runs the authorization machine. When there is already a session here, that is the
+ * answer, and it goes back to the opener immediately — no provider round trip, no PKCE exchange.
+ * When there is not, it forwards to the dispatcher (`next`), which owns that flow.
+ */
+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
+      }
+
+      if (token != null && token !== '') {
+        // Already signed in here. The framed application is the one that asked, so the session
+        // goes to it rather than being displayed to this window.
+        const outcome = await login.resume(token)
+        setStage(
+          outcome === LoginOutcome.Handled ? SurrogateStage.Handing
+            : outcome === LoginOutcome.Orphaned ? SurrogateStage.Orphaned
+              : SurrogateStage.Failed
+        )
+        return
+      }
+
+      // Nothing here yet — 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.
+      const next = query.get(LOGIN_NEXT_QUERY)
+      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) => {
+      console.error(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/service.ts

@@ -0,0 +1,19 @@
+import { appendLogin } from '@owlmeans/client-auth/login'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { makeRedirectLoginPlugin } from './redirect.js'
+import { makeSurrogateLoginPlugin } from './surrogate.js'
+
+/**
+ * Register the login host and the two browser flows on a context.
+ *
+ * Called by `makeContext`, so every web app has working login — including a framed one — without
+ * registering anything. An app that needs a different mechanic registers its own plugin at a
+ * higher priority; it does not replace this.
+ */
+export const appendWebLogin = <C extends BasicConfig, T extends BasicContext<C>>(ctx: T): T => {
+  const service = appendLogin<C, T>(ctx).login()
+  service.registerPlugin(makeRedirectLoginPlugin())
+  service.registerPlugin(makeSurrogateLoginPlugin())
+
+  return ctx
+}

package/src/login/surrogate.ts

@@ -0,0 +1,175 @@
+import {
+  adoptToken, clearSurrogate, markSurrogate, revokeToken, surrogatePath, LoginIntent, LoginOutcome,
+  LOGIN_LOGOUT_MESSAGE, LOGIN_SURROGATE_FEATURES, LOGIN_SURROGATE_NAME, LOGIN_TOKEN_MESSAGE,
+} 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'
+
+/**
+ * Login for a document that cannot complete the flow where it is.
+ *
+ * An app embedded in a frame cannot redirect to an identity provider: the provider refuses to be
+ * embedded (`frame-ancestors`), and its session cookies are third-party there. So the flow runs
+ * one window up, in a surrogate window that is top-level and first-party on this application's own
+ * origin — where the very same flow completes normally — and the token is passed back to the
+ * document that asked for it.
+ *
+ * This plugin is deliberately not OIDC-specific. The mechanic is "run the login route one window
+ * up and hand the token back", and the adoption is the plain auth service, so any relying party
+ * that renders a login route gets it by registering nothing.
+ *
+ * `match` covers BOTH halves of the lifecycle — the framed opener and the surrogate itself, where
+ * `embedded` is false. Inside the surrogate the redirect plugin must not win: that window IS
+ * 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 => {
+  /**
+   * 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
+    }
+
+    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()
+
+    return LoginOutcome.Handled
+  }
+
+  const plugin: LoginPlugin = {
+    alias: SURROGATE_LOGIN,
+    priority: SURROGATE_LOGIN_PRIORITY,
+    mode: 'surrogate',
+    match: env => env.hasWindow && (env.embedded || env.surrogate),
+
+    enter: () => { markSurrogate() },
+
+    begin: (ctx, request, env) => {
+      // Already one window up — nothing to open, just run the flow.
+      if (env.surrogate) {
+        window.location.href = request.url
+
+        return Promise.resolve(LoginOutcome.Redirected)
+      }
+
+      // 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, LOGIN_SURROGATE_FEATURES
+      )
+      if (surrogate == null) {
+        return Promise.resolve(LoginOutcome.Failed)
+      }
+
+      return awaitSurrogate(surrogate, LOGIN_TOKEN_MESSAGE, async data => {
+        if (data.token == null || data.token === '') {
+          return LoginOutcome.Failed
+        }
+        await adoptToken(ctx as LoginContext, 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?.()
+
+        return LoginOutcome.Handled
+      })
+    },
+
+    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.Redirected
+      }
+
+      // 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
+    },
+
+    complete: async (_ctx, token, env) => await handBack(token, env),
+
+    // 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 revokeToken(ctx as LoginContext)
+          .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, LOGIN_SURROGATE_FEATURES)
+        : 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 = revokeToken(ctx as LoginContext)
+      if (surrogate == null) {
+        return local.then(async () => {
+          await request.navigate?.()
+
+          return LoginOutcome.Failed
+        })
+      }
+
+      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
+      }
+      clearSurrogate()
+      window.opener.postMessage({ type: LOGIN_LOGOUT_MESSAGE, ok: true }, window.location.origin)
+      window.close()
+
+      return LoginOutcome.Handled
+    },
+  }
+
+  return plugin
+}

package/src/login/view.tsx

@@ -0,0 +1,94 @@
+import type { CSSProperties, FC } from 'react'
+import { LoginIntent } from '@owlmeans/client-auth/login'
+
+/** What the surrogate window is doing, from the point of view of the person watching it. */
+export enum SurrogateStage {
+  /** Working. No control — there is nothing for the user to do but wait. */
+  Working = 'working',
+  /** Needs a click: the flow cannot continue without a fresh gesture. */
+  Gesture = 'gesture',
+  /** Done here; handing the result back and closing. */
+  Handing = 'handing',
+  /** Acted, but with no channel back to the window that asked. */
+  Orphaned = 'orphaned',
+  /** Ended with nothing. */
+  Failed = 'failed',
+  /** Not a surrogate at all — someone opened this address directly. */
+  Standalone = 'standalone',
+}
+
+export interface SurrogateViewProps {
+  stage: SurrogateStage
+  intent: LoginIntent
+  onAction?: () => void
+  error?: string
+  translate?: (key: string, defaultValue: string) => string
+}
+
+/**
+ * The whole of what a login window shows.
+ *
+ * Plain elements and inline styles on purpose. This renders in a popup opened by a `web-panel` app,
+ * a `mui-panel` app and a generated Tailwind app alike, and none of their stylesheets is loaded
+ * here — a class name would simply do nothing. It is also the reason this component carries no
+ * dependency on a UI family at all.
+ */
+const box: CSSProperties = {
+  maxWidth: '22rem', margin: '15vh auto', padding: '1.5rem', textAlign: 'center',
+  fontFamily: 'system-ui, sans-serif', lineHeight: 1.5,
+}
+
+const action: CSSProperties = {
+  marginTop: '1rem', padding: '.625rem 1.25rem', fontSize: '1rem',
+  cursor: 'pointer', borderRadius: '.375rem', border: '1px solid currentColor',
+}
+
+const COPY: Record<SurrogateStage, { key: string, en: string, action?: [string, string] }> = {
+  [SurrogateStage.Working]: { key: 'working', en: 'Signing you in…' },
+  [SurrogateStage.Gesture]: {
+    key: 'gesture.title', en: 'Continue to sign in.', action: ['gesture.action', 'Sign in'],
+  },
+  [SurrogateStage.Handing]: { key: 'handing', en: 'Done. Returning to the application…' },
+  [SurrogateStage.Orphaned]: {
+    key: 'orphaned', en: 'Signed in. You can close this window and continue in the application.',
+    action: ['close', 'Close'],
+  },
+  [SurrogateStage.Failed]: {
+    key: 'failed', en: 'That did not complete. You can close this window and try again.',
+    action: ['close', 'Close'],
+  },
+  [SurrogateStage.Standalone]: {
+    key: 'standalone.title', en: 'This page is used to sign in from another window.',
+    action: ['standalone.action', 'Open the application'],
+  },
+}
+
+const LOGOUT_COPY: Partial<Record<SurrogateStage, { key: string, en: string }>> = {
+  [SurrogateStage.Working]: { key: 'working', en: 'Signing you out…' },
+  [SurrogateStage.Gesture]: { key: 'gesture.title', en: 'Continue to sign out.' },
+  [SurrogateStage.Handing]: { key: 'handing', en: 'Signed out. Returning to the application…' },
+  [SurrogateStage.Orphaned]: {
+    key: 'orphaned', en: 'Signed out. You can close this window.',
+  },
+  [SurrogateStage.Failed]: {
+    key: 'failed', en: 'Sign-out did not complete here. You can close this window.',
+  },
+}
+
+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

@@ -25,5 +25,14 @@ export const render = (node: ReactNode, opts?: RenderOptions) => {
   opts?.onReady ?? true ? window.addEventListener('DOMContentLoaded', _callback) : _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/modules.ts

@@ -1,9 +1,20 @@
-import { DISPATCHER } from '@owlmeans/auth'
+import { DISPATCHER, DISPATCHER_SURROGATE } from '@owlmeans/auth'
 import { modules as list } from '@owlmeans/client-auth'
 import { elevate } from '@owlmeans/client-entrypoint'
 import { handler } from '@owlmeans/client'
 import { Dispatcher } from './components/dispatcher/component.js'
+import { SurrogateScreen } from './login/screen.js'
 
 elevate(list, DISPATCHER, handler(Dispatcher), { force: true })
 
+/**
+ * Elevated here rather than in a relying-party package on purpose.
+ *
+ * The surrogate mechanic is not OIDC-specific — it is "run the login route one window up and hand
+ * the result back" — and every web application already spreads this list. Putting the screen here
+ * means `web-panel`, `mui-panel` and every generated target gain a working login window with no
+ * edit of their own, which is the only way an application that is already deployed can get it.
+ */
+elevate(list, DISPATCHER_SURROGATE, handler(SurrogateScreen))
+
 export const modules = list

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { AuthServiceAppend } from '@owlmeans/client-auth'
+import type { LoginServiceAppend } from '@owlmeans/client-auth/login'
 import type { ClientConfig } from '@owlmeans/client-context'
 import type { ClientContext } from '@owlmeans/client'
 
@@ -13,5 +14,5 @@ export interface AppConfig extends ClientConfig {
 }
 
 export interface AppContext<C extends AppConfig = AppConfig> extends ClientContext<C>,
-  AuthServiceAppend {
+  AuthServiceAppend, LoginServiceAppend {
 }