@owlmeans/client-auth 0.1.18-rc.10 → 0.1.18-rc.13

package/src/login/screen.tsx

@@ -0,0 +1,122 @@
+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 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, and renders the same credit line.
+ */
+const box: CSSProperties = {
+  maxWidth: '24rem', margin: '10vh auto', padding: '1.5rem',
+  fontFamily: 'system-ui, sans-serif', lineHeight: 1.5,
+}
+
+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 } : {}),
+})
+
+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 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>
+}

package/src/login/service.ts

@@ -1,10 +1,15 @@
 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 } from './adopt.js'
+import { adoptToken, revokeToken } from './adopt.js'
+import { resolveLoginMethods } from './methods.js'
 import { LoginOutcome } from './types.js'
-import type { LoginContext, LoginPlugin, LoginService, LoginServiceAppend } 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,
@@ -19,12 +24,16 @@ import type { LoginContext, LoginPlugin, LoginService, LoginServiceAppend } from
  * stage. `context.service()` throws for an uninitialized non-lazy service, which would make
  * `ensureLoginService` fail exactly where apps are told to call it.
  *
- * `begin` is 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`.
+ * `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
 
@@ -38,6 +47,33 @@ export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService =>
       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(
@@ -58,6 +94,13 @@ export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService =>
 
     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)
     },
@@ -74,7 +117,37 @@ export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService =>
       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

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).getPath()
+  } 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

@@ -1,4 +1,6 @@
+import type { ComponentType, 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.
@@ -37,12 +39,18 @@ export enum LoginOutcome {
   Redirected = 'redirected',
   /** Cannot proceed without a fresh user gesture — the caller renders a sign-in control. */
   Gesture = 'gesture',
-  /** Authenticated, but with no channel back to the window that started the flow. */
+  /** 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
@@ -56,6 +64,13 @@ export interface LoginRequest {
   target?: string
 }
 
+export interface LogoutRequest {
+  /** Where a surrogate logout runs — a resolved surrogate path. */
+  url: string
+  /** The in-app continuation once the local session is gone. */
+  navigate?: () => void | Promise<void>
+}
+
 /**
  * A pluggable login mechanic — WHERE the authorization round trip runs.
  *
@@ -95,14 +110,125 @@ export interface LoginPlugin {
 
   /** A bearer token was issued in this document — decide where it goes. */
   complete: (ctx: LoginContext, token: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /**
+   * This document ALREADY holds a session — decide whether it is useful here.
+   *
+   * Absent means `Passed`: keep it and carry on, which is what an ordinary tab has always done.
+   * A surrogate hands it back to its opener instead, which is the whole point: a popup that
+   * discovers an existing session must sign the framed application in, not display the
+   * application to itself.
+   *
+   * Deliberately not `complete`: "a token was just issued here" and "a token was already here"
+   * are different facts, and a silent-refresh plugin will need to tell them apart.
+   */
+  resume?: (ctx: LoginContext, token: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /**
+   * Start logout from a user gesture.
+   *
+   * MUST open any window synchronously, for exactly the reason `begin` must — logging out of a
+   * framed application opens a window too. Implement as a NON-async function.
+   */
+  logout?: (ctx: LoginContext, request: LogoutRequest, env: LoginEnv) => Promise<LoginOutcome>
+
+  /** The local session is gone in this document — decide what to tell whom. */
+  logoutComplete?: (ctx: LoginContext, env: LoginEnv) => Promise<LoginOutcome>
+}
+
+/**
+ * Something that must be true before a login flow may start.
+ *
+ * SYNCHRONOUS on purpose. `begin` must not cross a microtask boundary before a plugin's
+ * `window.open`, or the popup blocker eats the window. A precondition that has to ask a server
+ * belongs somewhere else entirely.
+ *
+ * Returning false stops the flow and resolves `begin` as {@link LoginOutcome.Gesture} — which
+ * already means "cannot proceed without a fresh user gesture; render a control", and is exactly
+ * the state a user is in after a blocking dialog has opened over the page.
+ */
+export interface LoginPrecondition {
+  alias: string
+  /** Higher runs first. Defaults to 0. */
+  priority?: number
+  check: (ctx: LoginContext, request: LoginRequest, env: LoginEnv) => boolean
 }
 
+/** What a source needs in order to describe the methods it offers. */
+export interface LoginMethodContext {
+  context: LoginContext
+  env: LoginEnv
+  /** In-app navigation, when a component supplied it. */
+  navigate?: (alias: string, params?: Record<string, string>) => void | Promise<void>
+}
+
+/**
+ * One way to sign in, as the screen renders it.
+ *
+ * `start` is what a button calls. It MUST be callable synchronously from a click — branch on
+ * `env.embedded && !env.surrogate` first and open any window before the first `await`.
+ */
+export interface LoginMethod {
+  id: string
+  /** Set when an `AuthenticationPlugin` drives this method. */
+  type?: string
+  label?: string
+  i18nKey?: string
+  icon?: string
+  order?: number
+  emphasis?: LoginMethodEmphasis
+  restricted?: boolean
+  params?: Record<string, string>
+  start: (ctx: LoginMethodContext) => Promise<LoginOutcome>
+}
+
+export interface LoginMethodSource {
+  alias: string
+  list: (ctx: LoginMethodContext) => LoginMethod[]
+}
+
+/** What every rendering of the sign-in screen accepts, whatever its UI family. */
+export interface LoginScreenProps {
+  /** The one thing a consuming application is expected to supply. */
+  Logo?: ComponentType<{ className?: string }> | ReactNode
+  title?: ReactNode
+  subtitle?: ReactNode
+  /**
+   * `(key, defaultValue) => string`. A prop, never an implicit context read: a component that
+   * reaches for an i18n provider crashes the whole render in an app mounted without one.
+   */
+  translate?: (key: string, defaultValue: string) => string
+  /** 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
+}
+
+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.
@@ -110,8 +236,13 @@ export interface LoginService extends LazyService {
   begin: (request: LoginRequest) => Promise<LoginOutcome>
   authorize: (url: string) => Promise<LoginOutcome>
   complete: (token: string) => Promise<LoginOutcome>
+  resume: (token: string) => Promise<LoginOutcome>
+  logout: (request: LogoutRequest) => Promise<LoginOutcome>
+  logoutComplete: () => Promise<LoginOutcome>
   /** Adopt an issued bearer token as this context's authentication. */
   adopt: (token: string) => Promise<void>
+  /** Drop this document's authentication. The single de-adoption path. */
+  revoke: () => Promise<void>
 }
 
 export interface LoginServiceAppend {

package/src/manager/plugins/basic-ed25519.tsx

@@ -7,6 +7,8 @@ import { AuthenCredError } from '../errors.js'
 export const ed25519BasicUIPlugin: AuthenticationPlugin = {
   type: AuthenticationType.BasicEd25519,
 
+  method: { order: 300, icon: 'key', emphasis: 'secondary' },
+
   Implementation: Renderer => ({ type, stage, control, params }) => {
 
     type = type ?? AuthenticationType.BasicEd25519

package/src/manager/plugins/exports.ts

@@ -1,4 +1,6 @@
 export type * from './types.js'
+export * from './registry.js'
+export * from './methods.js'
 export * from './tunnel/index.js'
 export * from './basic-ed25519.js'
 export * from './re-captcha.js'

package/src/manager/plugins/index.ts

@@ -1,13 +1,19 @@
-import type { ClientAuthType } from '../components/index.js'
-
 import { AuthenticationType } from '@owlmeans/auth'
 import { ed25519BasicUIPlugin } from './basic-ed25519.js'
-import { AuthenticationPlugin } from './types.js'
 import { reCaptchaPlugin } from './re-captcha.js'
 import { tunnelConsumerUIPlugin } from './tunnel-consumer.js'
+import { pluginMethodSource } from './methods.js'
+import { registerMethodSource } from '../../login/methods.js'
+import { plugins } from './registry.js'
 
-export const plugins: { [type: ClientAuthType]: AuthenticationPlugin } = {}
+export { plugins, registerAuthPlugin, getAuthPlugin, listAuthPlugins } from './registry.js'
 
 plugins[AuthenticationType.BasicEd25519] = ed25519BasicUIPlugin
 plugins[AuthenticationType.ReCaptcha] = reCaptchaPlugin
 plugins[AuthenticationType.WalletConsumer] = tunnelConsumerUIPlugin
+
+// Registered from here, not from `login/`, so that importing `@owlmeans/client-auth/login` never
+// drags this module's React plugin implementations into a bundle that only wanted the login host.
+// A generated application imports the login subpath through `client-iam`; it must not gain three
+// authentication methods it never registered as a side effect of that.
+registerMethodSource(pluginMethodSource)

package/src/manager/plugins/methods.ts

@@ -0,0 +1,52 @@
+import { CAUTHEN_AUTHEN_TYPED } from '@owlmeans/auth'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { DEFAULT_METHOD_ORDER, LOGIN_SERVICE } from '../../login/consts.js'
+import type { LoginMethod, LoginMethodSource, LoginService } from '../../login/types.js'
+import { listAuthPlugins } from './registry.js'
+
+/**
+ * Every registered authentication plugin that declares itself offerable, as a sign-in method.
+ *
+ * A plugin without `method` is deliberately invisible here: `re-captcha` is a STEP inside another
+ * flow, not a way to sign in, and a registry that offered everything registered would put it on
+ * the screen as a choice.
+ */
+export const pluginMethodSource: LoginMethodSource = {
+  alias: 'authentication-plugins',
+
+  list: () => listAuthPlugins()
+    .filter(plugin => plugin.method != null && plugin.method.hidden !== true)
+    .map((plugin): LoginMethod => {
+      const meta = plugin.method!
+      const type = plugin.type
+      const id = meta.id ?? type
+
+      return {
+        id, type,
+        ...(meta.label != null ? { label: meta.label } : {}),
+        i18nKey: meta.i18nKey ?? id,
+        ...(meta.icon != null ? { icon: meta.icon } : {}),
+        order: meta.order ?? DEFAULT_METHOD_ORDER,
+        ...(meta.emphasis != null ? { emphasis: meta.emphasis } : {}),
+        ...(meta.restricted === true ? { restricted: true } : {}),
+        params: { type },
+
+        // Non-async through the whole chain: `login.begin` opens the surrogate window in its first
+        // statement, and a window opened after the gesture has been handled is blocked.
+        start: methodCtx => {
+          const login = methodCtx.context.service<LoginService>(LOGIN_SERVICE)
+          const entrypoint = methodCtx.context.entrypoint<ClientEntrypoint>(CAUTHEN_AUTHEN_TYPED)
+          const url = entrypoint.getPath().replace(':type', encodeURIComponent(type))
+
+          return login.begin({
+            url,
+            // In an ordinary tab this keeps the application mounted, exactly as the pre-chooser
+            // dispatcher did; the surrogate plugin ignores it and opens a window instead.
+            ...(methodCtx.navigate != null
+              ? { navigate: () => methodCtx.navigate?.(CAUTHEN_AUTHEN_TYPED, { type }) }
+              : {}),
+          })
+        },
+      }
+    }),
+}

package/src/manager/plugins/re-captcha.tsx

@@ -5,6 +5,9 @@ import { useEffect } from 'react'
 export const reCaptchaPlugin: AuthenticationPlugin = {
   type: AuthenticationType.ReCaptcha,
 
+  // A STEP inside another flow, never a way to sign in — so it is registered and never offered.
+  method: { hidden: true },
+
   Implementation: Renderer => ({ type, stage, control, params }) => {
     Renderer = Renderer ?? reCaptchaPlugin.Renderer
 

package/src/manager/plugins/registry.ts

@@ -0,0 +1,26 @@
+import type { ClientAuthType } from '../components/authentication/types.js'
+import type { AuthenticationPlugin } from './types.js'
+
+/**
+ * The registry every authentication plugin lands in.
+ *
+ * It stays a plain exported object, and every registration stays a plain assignment, because four
+ * packages already write into it from side-effect imports (`web-oidc-rp`, `mui-oidc-rp`,
+ * `web-auth`, and this package's own `index`). Hiding it behind an API would break all of them for
+ * no gain — the functions below simply read it.
+ *
+ * It lives in its own module rather than in `index.ts` so that the method source can read it
+ * without the two importing each other.
+ */
+export const plugins: { [type: ClientAuthType]: AuthenticationPlugin } = {}
+
+export const registerAuthPlugin = (plugin: AuthenticationPlugin): AuthenticationPlugin => {
+  plugins[plugin.type] = plugin
+
+  return plugin
+}
+
+export const getAuthPlugin = (type: ClientAuthType): AuthenticationPlugin | undefined =>
+  plugins[type]
+
+export const listAuthPlugins = (): AuthenticationPlugin[] => Object.values(plugins)

package/src/manager/plugins/tunnel-consumer.tsx

@@ -13,6 +13,8 @@ import { createWalletFacade } from './tunnel/wallet.js'
 export const tunnelConsumerUIPlugin: AuthenticationPlugin = {
   type: AuthenticationType.WalletConsumer,
 
+  method: { order: 400, icon: 'wallet' },
+
   Implementation: renderer => ({ type, stage, control, params }) => {
     type = type ?? AuthenticationType.WalletConsumer
     const Renderer: TunnelAuthenticationRenderer | undefined = renderer

package/src/manager/plugins/types.ts

@@ -1,4 +1,5 @@
 import type { FC } from 'react'
+import type { LoginMethodEmphasis } from '@owlmeans/config'
 import type { AuthenticationControl, AuthenticationRenderer, AuthenticationRendererProps, } from '../components/authentication/types.js'
 
 export interface AuthenticationPlugin extends Pick<
@@ -7,6 +8,37 @@ export interface AuthenticationPlugin extends Pick<
   type: string
   Implementation: PluginImplemnetation
   Renderer?: AuthenticationRenderer
+  /**
+   * How this method presents itself on the sign-in screen.
+   *
+   * Absent means the plugin is never OFFERED — it is still reachable by type, which is what a
+   * step-in-a-flow (re-captcha) and a plugin an app deep-links to both need. Every field is
+   * optional so an existing plugin object keeps type-checking without being touched.
+   */
+  method?: AuthMethodMeta
+}
+
+export interface AuthMethodMeta {
+  /** Defaults to the plugin's `type`. */
+  id?: string
+  /** Literal fallback used when no translation resolves. */
+  label?: string
+  /** Key under the `auth` library's `login.method.*`; defaults to the id. */
+  i18nKey?: string
+  /** Icon registry NAME, never markup — this package must stay free of an icon library. */
+  icon?: string
+  /** Ascending; default 100. */
+  order?: number
+  emphasis?: LoginMethodEmphasis
+  /**
+   * Never offered unless the configuration explicitly enables it.
+   *
+   * This is the secret-key gate: an operator login is registered like any other method and must
+   * not become offerable merely by being registered.
+   */
+  restricted?: boolean
+  /** Registered, but never a choice. */
+  hidden?: boolean
 }
 
 export interface PluginImplemnetation {