@owlmeans/client-auth 0.1.18-rc.4 → 0.1.18-rc.41

package/src/login/methods.ts

@@ -0,0 +1,113 @@
+import type { LoginMethodConfig, LoginScreenConfig } from '@owlmeans/config'
+import { DEFAULT_METHOD_ORDER } from './consts.js'
+import type { LoginMethod, LoginMethodContext, LoginMethodSource } from './types.js'
+
+/**
+ * The module-global registry of method SOURCES.
+ *
+ * A source, rather than a method, because the two things that offer sign-in methods answer
+ * different questions at different times: the plugin registry knows what code is loaded, and the
+ * OIDC configuration knows what an entity is federated with. Both are answered per render — a
+ * provider list can arrive from the api-config middleware after the first paint.
+ *
+ * Global, like the `AuthenticationPlugin` map it mirrors, because a package registers its source
+ * from a side-effect import that has no context to hang it on. A context-scoped registry exists
+ * alongside it on the login service, and both are merged by {@link resolveLoginMethods}.
+ */
+const sources: LoginMethodSource[] = []
+
+export const registerMethodSource = (source: LoginMethodSource): void => {
+  const existing = sources.findIndex(candidate => candidate.alias === source.alias)
+  if (existing >= 0) {
+    sources.splice(existing, 1)
+  }
+  sources.push(source)
+}
+
+export const listMethodSources = (): LoginMethodSource[] => [...sources]
+
+/** Normalize a config entry, which may be a bare id or a full override object. */
+const asConfig = (entry: string | LoginMethodConfig): LoginMethodConfig =>
+  typeof entry === 'string' ? { id: entry } : entry
+
+const merge = (method: LoginMethod, override: LoginMethodConfig | undefined): LoginMethod =>
+  override == null ? method : {
+    ...method,
+    ...(override.label != null ? { label: override.label } : {}),
+    ...(override.i18nKey != null ? { i18nKey: override.i18nKey } : {}),
+    ...(override.icon != null ? { icon: override.icon } : {}),
+    ...(override.order != null ? { order: override.order } : {}),
+    ...(override.emphasis != null ? { emphasis: override.emphasis } : {}),
+    ...(override.params != null ? { params: { ...method.params, ...override.params } } : {}),
+  }
+
+/**
+ * Everything the current environment may be offered, in the order it should be offered in.
+ *
+ * Resolution order matters and is not arbitrary:
+ *
+ * 1. Sources produce candidates. A source that throws is skipped rather than taking the screen
+ *    down — a misconfigured provider list must not remove the sign-in method that does work.
+ * 2. `restricted` candidates are dropped unless the configuration named them, which is what makes
+ *    an operator login opt-in rather than merely unadvertised.
+ * 3. An explicit `methods` list is both a filter AND the order, because an app that bothered to
+ *    list them means that list.
+ */
+export const resolveLoginMethods = (
+  ctx: LoginMethodContext, cfg?: LoginScreenConfig, extra: LoginMethodSource[] = []
+): LoginMethod[] => {
+  const candidates: LoginMethod[] = []
+  for (const source of [...sources, ...extra]) {
+    try {
+      candidates.push(...source.list(ctx))
+    } catch (e) {
+      console.error(`login: method source "${source.alias}" failed`, e)
+    }
+  }
+
+  const overrides = cfg?.overrides ?? {}
+  const listed = cfg?.methods?.map(asConfig)
+  const listedIds = listed?.map(entry => entry.id).filter((id): id is string => id != null)
+
+  const offered = candidates
+    .filter(method => {
+      const override = overrides[method.id] ?? listed?.find(entry => entry.id === method.id)
+      if (override?.enabled === false || override?.hidden === true) {
+        return false
+      }
+      // A restricted method is offered only where the configuration asked for it — by naming it in
+      // `methods`, or by enabling it in `overrides`. Registering the plugin is deliberately not
+      // enough: an operator login that appears wherever its code happens to be bundled is an
+      // operator login in production.
+      if (method.restricted === true
+        && listedIds?.includes(method.id) !== true
+        && override?.enabled !== true) {
+        return false
+      }
+      return true
+    })
+    .map(method => merge(method, overrides[method.id]))
+
+  if (listedIds != null) {
+    return listedIds
+      .map(id => {
+        const method = offered.find(candidate => candidate.id === id)
+        return method != null ? merge(method, listed?.find(entry => entry.id === id)) : null
+      })
+      .filter((method): method is LoginMethod => method != null)
+  }
+
+  return offered.sort((a, b) => {
+    const order = (a.order ?? DEFAULT_METHOD_ORDER) - (b.order ?? DEFAULT_METHOD_ORDER)
+    return order !== 0 ? order : a.id.localeCompare(b.id)
+  })
+}
+
+/**
+ * The method a screen highlights and focuses.
+ *
+ * The first `primary` one, else the first offered. It is highlighted, never started: requirement
+ * one of this whole feature is that nothing leaves the document without a click.
+ */
+export const primaryLoginMethod = (methods: LoginMethod[]): LoginMethod | null =>
+  methods.find(method => method.emphasis === 'primary') ?? methods[0] ?? null

package/src/login/resume.ts

@@ -0,0 +1,58 @@
+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:
+    case LoginOutcome.Blocked:
+      // 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:
+    case LoginOutcome.Blocked:
+      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,195 @@
+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, LoginNotifier, 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
+  let notifier: LoginNotifier | 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,
+
+    registerNotifier: value => { notifier = value },
+
+    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)
+        }
+      }
+
+      // Notified here, in the facade, rather than by each caller: `useLogin` fires the flow and
+      // forgets the result, and this is the one place every caller — the header hook and the
+      // sign-in screen's method buttons alike — passes through on the way to a settled outcome.
+      return service.plugin(env).begin(ctx(), request, env).then(outcome => {
+        notifier?.(outcome, env)
+
+        return outcome
+      })
+    },
+
+    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).then(outcome => {
+        notifier?.(outcome, env)
+
+        return outcome
+      })
+    },
+
+    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()}`
+}