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

package/src/login/types.ts

@@ -0,0 +1,279 @@
+import type { ComponentType, CSSProperties, ReactNode } from 'react'
+import type { LazyService, BasicContext } from '@owlmeans/context'
+import type { LoginMethodEmphasis, LoginScreenConfig, LoginTermsConfig } from '@owlmeans/config'
+
+/**
+ * The context a login plugin is handed.
+ *
+ * Deliberately `BasicContext<any>`, matching `RouterService`: a plugin only ever reaches services
+ * by alias, and pinning the config parameter would make every concrete app config — each of which
+ * adds its own required fields — fail to satisfy it, since `makeContext` is invariant in it.
+ */
+export type LoginContext = BasicContext<any>
+
+/**
+ * Environment descriptor the cascade selects a login plugin on.
+ *
+ * This is the single source of environment truth — do NOT bake `window.self !== window.top` or a
+ * `sessionStorage` probe into a plugin's `match`. A native host will supply its own descriptor
+ * (`hasWindow: false`) so an in-app-browser plugin wins there without any DOM check.
+ */
+export interface LoginEnv {
+  /** A DOM is present at all (false under SSR, native, and unit tests). */
+  hasWindow: boolean
+  /** This document is embedded in a frame. A cross-origin `top` read throws — that throw counts. */
+  embedded: boolean
+  /** This document IS the surrogate login window; survives the cross-origin round trip. */
+  surrogate: boolean
+  /** The window that opened this one is still reachable (COOP severs it permanently). */
+  hasOpener: boolean
+}
+
+/** What a stage did, and therefore what the caller must do next. */
+export enum LoginOutcome {
+  /** The plugin took the flow over and it is finished. The caller does nothing more. */
+  Handled = 'handled',
+  /** The plugin did nothing — the caller carries on with its ordinary continuation. */
+  Passed = 'passed',
+  /** The browser is leaving this document. The caller must not navigate or render. */
+  Redirected = 'redirected',
+  /** Cannot proceed without a fresh user gesture — the caller renders a sign-in control. */
+  Gesture = 'gesture',
+  /** Authenticated, but with no channel back to the window that started it. */
+  Orphaned = 'orphaned',
+  /** The attempt ended with no token (the user closed the window, or the provider refused it). */
+  Failed = 'failed',
+  /**
+   * A window this flow needed could not be opened at all — `window.open` returned `null`, which is
+   * the browser's own popup blocker, not a flow failure. Distinct from {@link Failed}: a caller
+   * with nowhere inline to render (a header "Log in"/"Log out" control, not the sign-in screen)
+   * needs to know specifically that a fresh click reopening the SAME control will not help, and
+   * that the browser is already showing its own blocked-popup affordance somewhere.
+   */
+  Blocked = 'blocked',
+}
+
+/** Why a surrogate window was opened. */
+export enum LoginIntent {
+  Login = 'login',
+  Logout = 'logout',
+}
+
+export interface LoginRequest {
+  /** Where the login flow starts — a resolved dispatcher path, or the current address. */
+  url: string
+  /**
+   * The ordinary in-app continuation, supplied by the caller because only a component may call
+   * `useNavigate`. A plugin that decides not to take the flow over calls this; without it the
+   * fallback is a full page load of {@link url}.
+   */
+  navigate?: () => void | Promise<void>
+  /** Entrypoint alias to return to after login. */
+  target?: string
+}
+
+export interface LogoutRequest {
+  /** Where a surrogate logout runs — a resolved surrogate path. */
+  url: string
+  /** The in-app continuation once the local session is gone. */
+  navigate?: () => void | Promise<void>
+}
+
+/**
+ * A pluggable login mechanic — WHERE the authorization round trip runs.
+ *
+ * Not to be confused with `AuthenticationPlugin` (./manager/plugins), which answers *how* a user
+ * proves their identity. This one answers *in which browsing context the flow can complete*: a
+ * redirect works in an ordinary tab and cannot work inside a frame whose provider refuses to be
+ * embedded, and that difference is a property of the environment, not of the credential.
+ */
+export interface LoginPlugin {
+  alias: string
+  /** Higher wins among matching plugins. Defaults to 0. */
+  priority?: number
+  /** Free-form tag, e.g. 'redirect' | 'surrogate' | 'native'. */
+  mode?: string
+  /** Selector; `undefined` means "always applicable". */
+  match?: (env: LoginEnv, ctx?: LoginContext) => boolean
+
+  /**
+   * Record, while it is still knowable, whatever the later stages need about this document.
+   *
+   * Called synchronously as the FIRST statement of the dispatcher's effect: everything after it
+   * can navigate away, and some of the evidence (notably `window.name`) is cleared by the browser
+   * the moment a top-level context goes cross-origin.
+   */
+  enter?: (ctx: LoginContext, env: LoginEnv) => void
+
+  /**
+   * Start login from a user gesture.
+   *
+   * MUST open any window synchronously — the popup blocker only yields while the gesture is still
+   * being handled. Implement as a NON-async function returning a promise.
+   */
+  begin: (ctx: LoginContext, request: LoginRequest, env: LoginEnv) => Promise<LoginOutcome>
+
+  /** Send the browser to the identity provider's authorization URL. */
+  authorize: (ctx: LoginContext, url: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /** A bearer token was issued in this document — decide where it goes. */
+  complete: (ctx: LoginContext, token: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /**
+   * This document ALREADY holds a session — decide whether it is useful here.
+   *
+   * Absent means `Passed`: keep it and carry on, which is what an ordinary tab has always done.
+   * A surrogate hands it back to its opener instead, which is the whole point: a popup that
+   * discovers an existing session must sign the framed application in, not display the
+   * application to itself.
+   *
+   * Deliberately not `complete`: "a token was just issued here" and "a token was already here"
+   * are different facts, and a silent-refresh plugin will need to tell them apart.
+   */
+  resume?: (ctx: LoginContext, token: string, env: LoginEnv) => Promise<LoginOutcome>
+
+  /**
+   * Start logout from a user gesture.
+   *
+   * MUST open any window synchronously, for exactly the reason `begin` must — logging out of a
+   * framed application opens a window too. Implement as a NON-async function.
+   */
+  logout?: (ctx: LoginContext, request: LogoutRequest, env: LoginEnv) => Promise<LoginOutcome>
+
+  /** The local session is gone in this document — decide what to tell whom. */
+  logoutComplete?: (ctx: LoginContext, env: LoginEnv) => Promise<LoginOutcome>
+}
+
+/**
+ * Something that must be true before a login flow may start.
+ *
+ * SYNCHRONOUS on purpose. `begin` must not cross a microtask boundary before a plugin's
+ * `window.open`, or the popup blocker eats the window. A precondition that has to ask a server
+ * belongs somewhere else entirely.
+ *
+ * Returning false stops the flow and resolves `begin` as {@link LoginOutcome.Gesture} — which
+ * already means "cannot proceed without a fresh user gesture; render a control", and is exactly
+ * the state a user is in after a blocking dialog has opened over the page.
+ */
+export interface LoginPrecondition {
+  alias: string
+  /** Higher runs first. Defaults to 0. */
+  priority?: number
+  check: (ctx: LoginContext, request: LoginRequest, env: LoginEnv) => boolean
+}
+
+/** What a source needs in order to describe the methods it offers. */
+export interface LoginMethodContext {
+  context: LoginContext
+  env: LoginEnv
+  /** In-app navigation, when a component supplied it. */
+  navigate?: (alias: string, params?: Record<string, string>) => void | Promise<void>
+}
+
+/**
+ * One way to sign in, as the screen renders it.
+ *
+ * `start` is what a button calls. It MUST be callable synchronously from a click — branch on
+ * `env.embedded && !env.surrogate` first and open any window before the first `await`.
+ */
+export interface LoginMethod {
+  id: string
+  /** Set when an `AuthenticationPlugin` drives this method. */
+  type?: string
+  label?: string
+  i18nKey?: string
+  icon?: string
+  order?: number
+  emphasis?: LoginMethodEmphasis
+  restricted?: boolean
+  params?: Record<string, string>
+  start: (ctx: LoginMethodContext) => Promise<LoginOutcome>
+}
+
+export interface LoginMethodSource {
+  alias: string
+  list: (ctx: LoginMethodContext) => LoginMethod[]
+}
+
+/** What every rendering of the sign-in screen accepts, whatever its UI family. */
+export interface LoginScreenProps {
+  /** The one thing a consuming application is expected to supply. */
+  Logo?: ComponentType<{ className?: string }> | ReactNode
+  title?: ReactNode
+  subtitle?: ReactNode
+  /**
+   * `(key, defaultValue) => string`. A prop, never an implicit context read: a component that
+   * reaches for an i18n provider crashes the whole render in an app mounted without one.
+   */
+  translate?: (key: string, defaultValue: string) => string
+  /** Replace or reorder what the resolver produced. */
+  methods?: LoginMethod[] | ((methods: LoginMethod[]) => LoginMethod[])
+  terms?: LoginTermsConfig | false
+  config?: LoginScreenConfig
+  /** Replaces the composed credit line entirely. */
+  footer?: ReactNode
+  className?: string
+  containerClassName?: string
+  /**
+   * Inline overrides for the screen's outer box.
+   *
+   * It exists because the outer box carries its viewport height inline rather than as a utility
+   * class, and an escape hatch that a class can no longer provide has to be provided some other
+   * way. See the note on the screen itself.
+   */
+  style?: CSSProperties
+}
+
+export type LoginScreenComponent = ComponentType<LoginScreenProps>
+
+/**
+ * A way to surface a `begin`/`logout` outcome that has no inline screen to render it on.
+ *
+ * A header "Log in"/"Log out" control (`useLogin`/`useLogout`) fires the facade and forgets the
+ * result — it renders nothing of its own, unlike the sign-in screen, which already shows
+ * `loginAttemptError` inline. Registering one is how a UI package (`web-panel`, `mui-panel`) gives
+ * that control a way to speak — e.g. a toast when {@link LoginOutcome.Blocked} fires. Unregistered,
+ * it is silence, which is what a non-DOM host and a screen-mounted flow both already have.
+ */
+export type LoginNotifier = (outcome: LoginOutcome, env: LoginEnv) => void
+
+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
+  /** See {@link LoginNotifier}. Replaces any previously registered notifier. */
+  registerNotifier: (notifier: LoginNotifier) => void
+  // Facade — every method re-selects the plugin and delegates.
+  // NOTE: these stay plain writable instance properties, never getters, so that alternative
+  // implementations (e.g. a native login service) can monkey-patch them directly.
+  enter: () => void
+  begin: (request: LoginRequest) => Promise<LoginOutcome>
+  authorize: (url: string) => Promise<LoginOutcome>
+  complete: (token: string) => Promise<LoginOutcome>
+  resume: (token: string) => Promise<LoginOutcome>
+  logout: (request: LogoutRequest) => Promise<LoginOutcome>
+  logoutComplete: () => Promise<LoginOutcome>
+  /** Adopt an issued bearer token as this context's authentication. */
+  adopt: (token: string) => Promise<void>
+  /** Drop this document's authentication. The single de-adoption path. */
+  revoke: () => Promise<void>
+}
+
+export interface LoginServiceAppend {
+  login: () => LoginService
+}

package/src/manager/README.md

@@ -21,9 +21,9 @@ React components that handle various authentication scenarios:
 - **Tunnel Consumer**: Component for handling WebSocket authentication tunnels
 - **Credential Management**: Secure handling of user credentials
 
-### Module Integration
-The manager integrates with the OwlMeans module system to provide:
-- **Elevated Modules**: Enhanced modules with client-specific authentication handling
+### Entrypoint Integration
+The manager integrates with the OwlMeans entrypoint system to provide:
+- **Enhanced Entrypoints**: Entrypoints with client-specific authentication handling
 - **Route Protection**: Automatic authentication requirements for protected routes
 - **API Integration**: Seamless integration with authentication APIs
 
@@ -37,7 +37,7 @@ Comprehensive error handling for authentication scenarios:
 This manager is part of the `@owlmeans/client-auth` package:
 
 ```bash
-npm install @owlmeans/client-auth
+npm install @owlmeans/client-auth@^0.1.18-rc.41
 ```
 
 ## API Reference
@@ -134,37 +134,22 @@ try {
 }
 ```
 
-### Modules
+### Entrypoints
 
-#### `modules`
-Pre-configured authentication modules for client applications.
-
-```typescript
-const modules: CommonModule[]
-```
-
-Contains elevated modules for:
-- `AUTHEN` - Base authentication module
-- `AUTHEN_INIT` - Authentication initialization
-- `AUTHEN_AUTHEN` - User authentication
-- `AUTHEN_RELY` - Authentication relay
-- `CAUTHEN` - Client authentication
-- `CAUTHEN_AUTHEN` - Client authentication handler
-- `CAUTHEN_AUTHEN_DEFAULT` - Default authentication component
-- `CAUTHEN_AUTHEN_TYPED` - Typed authentication component
-- `DISPATCHER` - Authentication dispatcher
+#### `entrypoints`
+The shared, immutable authentication declarations. Bind them into the client context alongside
+the application's own entrypoints.
 
 ## Usage Examples
 
 ### Basic Authentication Setup
 
 ```typescript
-import { modules } from '@owlmeans/client-auth/manager'
-import { makeClientContext } from '@owlmeans/client-context'
+import { entrypoints } from '@owlmeans/client-auth/manager'
+import { makeContext } from '@owlmeans/web-client'
 
-// Register authentication modules with context
-const context = makeClientContext(config)
-context.registerModules(modules)
+const context = makeContext(config)
+context.registerEntrypoints(entrypoints)
 
 await context.configure().init()
 ```
@@ -256,48 +241,27 @@ function RealtimeApp() {
 
 ### Custom Authentication Flow
 
-```typescript
-import { modules, AuthenCredError } from '@owlmeans/client-auth/manager'
-import { useModule } from '@owlmeans/client'
+Use the typed authentication protocols from `@owlmeans/auth-common`; the context supplies the
+registered client binding and infers the request and response types from the protocol.
 
-function CustomAuthFlow() {
-  const authModule = useModule('auth')
-  
-  const handleLogin = async (credentials) => {
-    try {
-      const initResponse = await authModule.init({
-        type: AuthenticationType.PasswordLogin
-      })
-      
-      const authResponse = await authModule.authenticate({
-        ...credentials,
-        challenge: initResponse.challenge
-      })
-      
-      console.log('Authentication successful:', authResponse)
-    } catch (error) {
-      if (error instanceof AuthenCredError) {
-        console.error('Invalid credentials:', error.message)
-      } else {
-        console.error('Authentication failed:', error)
-      }
-    }
+```typescript
+import { AuthenticationType } from '@owlmeans/auth'
+import { authProtocols } from '@owlmeans/auth-common'
+import { AuthenCredError } from '@owlmeans/client-auth/manager'
+import type { ClientContext } from '@owlmeans/client-context'
+
+async function authenticate(context: ClientContext, credentials: { username: string, password: string }) {
+  try {
+    const allowance = await context.entrypoint(authProtocols.init).call({
+      body: { type: AuthenticationType.PasswordLogin },
+    })
+    return await context.entrypoint(authProtocols.authenticate).call({
+      body: { ...credentials, challenge: allowance.challenge },
+    })
+  } catch (error) {
+    if (error instanceof AuthenCredError) console.error('Invalid credentials:', error.message)
+    throw error
   }
-
-  return (
-    <form onSubmit={(e) => {
-      e.preventDefault()
-      const formData = new FormData(e.target)
-      handleLogin({
-        username: formData.get('username'),
-        password: formData.get('password')
-      })
-    }}>
-      <input name="username" placeholder="Username" required />
-      <input name="password" type="password" placeholder="Password" required />
-      <button type="submit">Login</button>
-    </form>
-  )
 }
 ```
 
@@ -408,18 +372,11 @@ Single-use token authentication for enhanced security.
 5. **Graceful Fallbacks**: Provide fallback UI for authentication failures
 6. **Security**: Never store sensitive credentials in local storage
 
-## Module Elevation
-
-The manager uses module elevation to enhance base authentication modules:
-
-```typescript
-// Base modules are elevated with client-specific handlers
-elevate(list, AUTHEN_INIT, true)           // API call elevation
-elevate(list, AUTHEN_AUTHEN, true)         // Authentication elevation
-elevate(list, CAUTHEN_AUTHEN_DEFAULT, handler(AuthenticationHOC()))  // Component handler
-```
+## Entrypoint wiring
 
-This provides seamless integration between the module system and React components.
+The manager exports a ready-to-use `entrypoints` collection. Compose it with the application's
+own declarations and use `bind`/`bindScreen` from `@owlmeans/client-entrypoint` when adding a
+custom client handler; handlers are attached to declaration objects, never looked up by alias.
 
 ## Dependencies
 
@@ -427,7 +384,7 @@ This manager depends on:
 - `@owlmeans/auth` - Core authentication functionality
 - `@owlmeans/auth-common` - Shared authentication components
 - `@owlmeans/client` - Client-side framework functionality
-- `@owlmeans/client-module` - Client module system
+- `@owlmeans/client-entrypoint` - Typed protocol binding system
 - `@owlmeans/error` - Error management system
 - `react` - React framework for UI components
 
@@ -436,4 +393,4 @@ This manager depends on:
 - [`@owlmeans/client-auth`](../../../README.md) - Parent client authentication package
 - [`@owlmeans/server-auth/manager`](../../../server-auth/src/manager/README.md) - Server-side authentication manager
 - [`@owlmeans/auth`](../../../auth/README.md) - Core authentication library
-- [`@owlmeans/client`](../../../client/README.md) - Client-side framework
+- [`@owlmeans/client`](../../../client/README.md) - Client-side framework

package/src/manager/components/authentication/control.ts

@@ -45,7 +45,7 @@ export const makeControl = (
       control.afterAuthenticate = plugins[control.type].afterAuthenticate
 
       const module = context.entrypoint<ClientEntrypoint<AllowanceResponse>>(AUTHEN_INIT)
-      const [allowance] = await module.call({ body: control.request })
+      const allowance = await module.call({ body: control.request })
 
       control.allowance = allowance
 
@@ -89,8 +89,8 @@ export const makeControl = (
         // We return back unwrapped challenge
         credentials.challenge = control.allowance?.challenge
 
-        const [token, status] = await context.entrypoint<ClientEntrypoint<AuthToken>>(AUTHEN_AUTHEN)
-          .call({ body: credentials })
+        const { value: token, outcome: status } = await context.entrypoint<ClientEntrypoint<AuthToken>>(AUTHEN_AUTHEN)
+          .invoke({ body: credentials })
 
         if (status === EntrypointOutcome.Ok && token.token != null
           && token.token !== '' && control.afterAuthenticate != null) {

package/src/manager/components/authentication/types.ts

@@ -2,7 +2,7 @@ import type {
   AllowanceRequest, AllowanceResponse, AuthCredentials, AuthenticationStage, AuthenticationType,
   AuthToken
 } from '@owlmeans/auth'
-import type { ModuleContextParams } from '@owlmeans/client'
+import type { EntrypointContextParams } from '@owlmeans/client'
 import type { FC } from 'react'
 import type { ClientContext } from '@owlmeans/client'
 import type { FlowService } from '@owlmeans/client-flow'
@@ -10,7 +10,7 @@ import type { ResilientError } from '@owlmeans/error'
 
 export type ClientAuthType = AuthenticationType | string
 
-export interface AuthenticationProps extends ModuleContextParams {
+export interface AuthenticationProps extends EntrypointContextParams {
   type?: ClientAuthType
   callback?: AuthenticationCallback
   source?: string

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

@@ -2,11 +2,11 @@ import { AuthenticationType } from '@owlmeans/auth'
 import { AuthenticationHOC } from './authentication/component.js'
 import type { FC } from 'react'
 import { useMemo } from 'react'
-import { useModule } from '@owlmeans/client'
+import { useEntrypoint } from '@owlmeans/client'
 import type { TunnelAuthenticationProps } from './types.js'
 
 export const TunnelConsumer: FC<Partial<TunnelAuthenticationProps>> = ({ ...props }) => {
-  const mod = useModule()
+  const mod = useEntrypoint()
   const Implementation = useMemo(
     () => AuthenticationHOC(undefined, AuthenticationType.WalletConsumer), []
   )

package/src/manager/entrypoints.ts

@@ -0,0 +1,18 @@
+
+import { authProtocols } from '@owlmeans/auth-common'
+import { handler } from '@owlmeans/client'
+import { bind, bindScreen, stab } from '@owlmeans/client-entrypoint'
+import { AuthenticationHOC } from './components/authentication/component.js'
+
+/** Browser entrypoints for the manager's authentication flows. */
+export const entrypoints = [
+  bind(authProtocols.authen),
+  bind(authProtocols.init),
+  bind(authProtocols.authenticate),
+  bind(authProtocols.rely),
+  bind(authProtocols.client),
+  bind(authProtocols.login),
+  bindScreen(authProtocols.loginDefault, handler(AuthenticationHOC())),
+  bindScreen(authProtocols.loginTyped, handler(AuthenticationHOC())),
+  bindScreen(authProtocols.dispatcher, stab),
+]

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

@@ -7,6 +7,13 @@ import { AuthenCredError } from '../errors.js'
 export const ed25519BasicUIPlugin: AuthenticationPlugin = {
   type: AuthenticationType.BasicEd25519,
 
+  method: { order: 300, icon: 'key', emphasis: 'secondary' },
+
+  // This package ships no UI family, so the form below is a `Renderer` a panel package assigns
+  // (`@owlmeans/web-panel/auth/plugins`, `@owlmeans/mui-panel/auth/plugins`). Until one does, the
+  // Implementation throws on mount — so the sign-in screen must not offer the method.
+  requiresRenderer: true,
+
   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,74 @@
+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, LoginMethodContext, LoginMethodSource, LoginService } from '../../login/types.js'
+import type { AuthenticationPlugin } from './types.js'
+import { listAuthPlugins } from './registry.js'
+
+/**
+ * Whether a registered plugin may be put on the sign-in screen of THIS application.
+ *
+ * The registry is global and is filled by side-effect imports, so "registered" means only that
+ * some module was pulled into the bundle — three separate reasons why that is not enough:
+ *
+ * 1. No `method`: `re-captcha` is a STEP inside another flow, not a way to sign in.
+ * 2. No renderer: a plugin that declares `requiresRenderer` throws the moment its screen mounts
+ *    unless a UI package (`web-panel`, `mui-panel`) assigned one. An app that imported the plugin
+ *    host without that package would be offering buttons whose only outcome is a broken page.
+ * 3. Not wired: a plugin whose flow needs a service its context never appended fails on the
+ *    lookup instead. Packages register their plugins in groups, so an app that wanted one of them
+ *    gets the rest too, and the rest have to be able to say they do not apply here.
+ */
+const offerable = (plugin: AuthenticationPlugin, ctx: LoginMethodContext): boolean => {
+  if (plugin.method == null || plugin.method.hidden === true) {
+    return false
+  }
+  if (plugin.requiresRenderer === true && plugin.Renderer == null) {
+    return false
+  }
+
+  return plugin.method.available?.(ctx) !== false
+}
+
+/**
+ * Every registered authentication plugin that declares itself offerable, as a sign-in method.
+ */
+export const pluginMethodSource: LoginMethodSource = {
+  alias: 'authentication-plugins',
+
+  list: ctx => listAuthPlugins()
+    .filter(plugin => offerable(plugin, ctx))
+    .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.path().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,13 @@ 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 },
+
+  // Its widget is a `Renderer` a panel package assigns. `hidden` already keeps it off the sign-in
+  // screen; this is what the flow that DOES drive it can check before handing it a stage.
+  requiresRenderer: true,
+
   Implementation: Renderer => ({ type, stage, control, params }) => {
     Renderer = Renderer ?? reCaptchaPlugin.Renderer