@owlmeans/client-auth 0.1.18-rc.6 → 0.1.18-rc.61

package/README.md

@@ -1,72 +1,318 @@
 # @owlmeans/client-auth
 
-Client-side authentication service providing user auth state and external auth flow setup.
-
-## Overview
-
-- `useSelfAuth()` — React hook that returns the current authenticated user's `Auth` object
-- `setupExternalAuthentication()` — configure the client to authenticate against an external identity provider
-- `modules` — pre-built client modules for the auth flow (login, dispatcher)
-- `DEFAULT_ALIAS` — the auth service alias (`'auth'`)
+The browser side of OwlMeans authentication: the client `AuthService` that holds the bearer token,
+the dispatcher HOC that handles the authentication return leg, the authentication-plugin registry
+and screen (`./manager`), and the login-plugin host with its sign-in method registry, terms
+confirmation and `useLogin` / `useLogout` hooks (`./login`). A web app normally gets the auth
+service and the login host from `@owlmeans/web-client`'s `makeContext`, and the styled sign-in
+screen from `@owlmeans/web-panel`. It imports this package for the hooks, the dispatcher contract
+and plugin authoring. The OIDC relying party is `@owlmeans/web-oidc-rp` (`@owlmeans/mui-oidc-rp` is
+legacy). The server-side counterpart is `@owlmeans/server-auth`.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/client-auth
+bun add @owlmeans/client-auth@^0.1.18-rc.61
 ```
 
+## Concepts
+
+- **Auth service** — `context.auth()`. The token lives in the `AUTH_RESOURCE` resource under the
+  single id `USER_ID`. `authenticated()` resolves to the token or `null`, `user()` returns the
+  decoded `Auth` (throwing `AuthorizationError` when there is none), and `update(token | undefined)`
+  adopts or drops a session.
+- **Dispatcher** — `DispatcherHOC` wraps a renderer that reads the return-leg query. It hands the
+  renderer `provideToken(token, query)` and `navigate()`, adopts the token, and strips `AUTH_QUERY`
+  before navigating on.
+- **Authentication plugin** (`./manager/plugins`) — *how* a person proves identity: `type`,
+  `Implementation`, an optional `Renderer` a UI package supplies, and `method` metadata when it is
+  offered on the sign-in screen.
+- **Login plugin** (`./login`) — *where* the round trip runs. Plugins are selected by `LoginEnv`
+  (embedded, surrogate) and priority. `@owlmeans/web-client` registers the redirect and surrogate
+  plugins.
+- **Login method** — one offerable button. `LoginMethodSource`s produce candidates;
+  `loginMethodsHelper.resolveLoginMethods` drops restricted ones the config did not name and applies the configured
+  order.
+- **Login outcome** — `LoginOutcome` (`Handled`, `Passed`, `Redirected`, `Gesture`, `Orphaned`,
+  `Failed`) tells the caller what to do next. `loginResumeHelper.resumeAction` and `.loginAttemptError` are the only
+  readings of it.
+
 ## Usage
 
-Access current auth state in a component:
+### 1. A context built by hand
+
+`@owlmeans/web-client`'s `makeContext` already does this. Only a context composed without it
+registers the pieces itself.
+
+```ts
+import { makeClientContext } from '@owlmeans/client'
+import { appendAuthService, bindExternalAuthentication, entrypoints as authEntrypoints } from '@owlmeans/client-auth'
+import { appendLogin } from '@owlmeans/client-auth/login'
+import { MY_APP_WEB } from 'my-app-common'
+import type { Config, Context } from './types.js'
+
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeClientContext(cfg) as T
+  appendAuthService<C, T>(context)   // registers under DEFAULT_ALIAS ('auth'), exposes context.auth()
+  appendLogin<C, T>(context)         // registers the login host, exposes context.login()
+
+  return context
+}
+
+export const clientBindings = [
+  ...authEntrypoints,
+  // The screen an external provider redirects into, pinned to this app's service.
+  bindExternalAuthentication(MY_APP_WEB),
+]
+```
+
+### 2. Guarding a layout and reading the identity
 
-```typescript
+```tsx
+import { authHelper } from '@owlmeans/auth'
 import { useSelfAuth } from '@owlmeans/client-auth'
+import type { FC, PropsWithChildren } from 'react'
+import { useContext } from '../context.js'
 
-function UserMenu() {
-  const auth = useSelfAuth()
-  return <span>{auth?.userId}</span>
+export const UserLayout: FC<PropsWithChildren> = ({ children }) => {
+  // `true` navigates to DISPATCHER when there is no session.
+  const authenticated = useSelfAuth(true)
+  const context = useContext()
+
+  if (!authenticated) {
+    return null
+  }
+
+  const auth = context.auth().user()
+  // The organization is its renameable entitySlug; the stable entityId never reaches the browser.
+  const organization = authHelper.entitySlugOf(auth)
+
+  return <main data-organization={organization}>{children}</main>
 }
 ```
 
-Set up external authentication (e.g. OIDC redirect):
+### 3. Sign-in and sign-out controls
 
-```typescript
-import { setupExternalAuthentication } from '@owlmeans/client-auth'
+```tsx
+import type { FC } from 'react'
+import { useLogin, useLogout } from '@owlmeans/client-auth/login'
 
-// In context setup
-setupExternalAuthentication(context, { serviceUrl: process.env.AUTH_URL })
+export const HeaderActions: FC<{ authenticated: boolean | null }> = ({ authenticated }) => {
+  const [loginPath, onLogIn] = useLogin()
+  const onLogOut = useLogout()
+
+  if (authenticated == null) {
+    return null
+  }
+
+  return authenticated
+    ? <button type="button" onClick={onLogOut}>Log out</button>
+    : <a href={loginPath} onClick={onLogIn}>Log in</a>
+}
 ```
 
+One control and one handler, with no conditions around them. The login service decides whether the
+flow redirects this tab or runs one window up, because the app is framed.
+
+### 4. Offering a sign-in method and gating the flow
+
+```ts
+import { ensureLoginService, LoginOutcome } from '@owlmeans/client-auth/login'
+import type { LoginMethodSource, LoginPrecondition } from '@owlmeans/client-auth/login'
+
+const partnerMethods: LoginMethodSource = {
+  alias: 'my-app-partner-methods',
+  list: () => [{
+    id: 'partner-sso',
+    label: 'Partner SSO',
+    i18nKey: 'partner',
+    icon: 'building',
+    order: 20,
+    // Callable synchronously from the click: leave before the first await.
+    start: () => {
+      window.location.href = partnerAuthorizeUrl()
+
+      return Promise.resolve(LoginOutcome.Redirected)
+    },
+  }],
+}
+
+const maintenanceWindow: LoginPrecondition = {
+  alias: 'my-app-maintenance',
+  // Synchronous by contract — a precondition that asks a server belongs elsewhere.
+  check: () => !isMaintenanceBannerOpen(),
+}
+
+export const appendPartnerLogin = <C extends Config, T extends Context<C>>(context: T): T => {
+  const login = ensureLoginService(context)
+  login.registerMethodSource(partnerMethods)
+  login.registerPrecondition(maintenanceWindow)
+
+  return context
+}
+```
+
+### 5. Authoring an authentication plugin
+
+```tsx
+import { AuthenticationStage } from '@owlmeans/auth'
+import type { AuthenticationRendererProps } from '@owlmeans/client-auth/manager'
+import { authPluginHelper } from '@owlmeans/client-auth/manager/plugins'
+import type { AuthenticationPlugin } from '@owlmeans/client-auth/manager/plugins'
+import { useEffect } from 'react'
+
+const MY_APP_PASSKEY = 'my-app-passkey'
+
+export const passkeyPlugin: AuthenticationPlugin = {
+  type: MY_APP_PASSKEY,
+  method: { label: 'Passkey', icon: 'key', order: 50 },
+  // The form comes from a UI package; without one the screen must not offer the method.
+  requiresRenderer: true,
+  Implementation: Renderer => ({ type, stage, control, params }: AuthenticationRendererProps) => {
+    useEffect(() => {
+      if (control.stage === AuthenticationStage.Init) {
+        void control.requestAllowence()
+      }
+    }, [type])
+
+    if (Renderer == null) {
+      throw new SyntaxError(`Renderer is not defined for ${MY_APP_PASSKEY}`)
+    }
+
+    return <Renderer type={type} stage={stage} control={control} params={params} />
+  },
+}
+
+authPluginHelper.registerAuthPlugin(passkeyPlugin)
+```
+
+A UI package then assigns `plugins[MY_APP_PASSKEY].Renderer`, and the renderer calls
+`control.authenticate({ userId, credential })` once the person has answered the challenge.
+
 ## API
 
-### `useSelfAuth(): Auth | null`
+### `@owlmeans/client-auth`
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeAuthService(alias?)` | function | The client `AuthService` — `authenticate`, `update`, `authenticated`, `user`, `store` |
+| `appendAuthService(ctx, alias?)` | function | Register it and `authMiddleware`; expose `context.auth()` |
+| `entrypoints` | const | `[bind(authProtocols.dispatcherAuthenticate)]` |
+| `bindExternalAuthentication(service)` | function | Bind `authProtocols.flowEnter` as a URL-only screen on the given service |
+| `useSelfAuth(force = true)` | hook | Resolves to `boolean`; navigates to `DISPATCHER` when unauthenticated and `force` is set |
+| `useWs(entrypoint, request?, options?)` | hook | `@owlmeans/client-socket`'s `useWs` with the token in `AUTH_QUERY`, refreshed before every reconnect unless the caller supplied its own |
+| `DispatcherHOC` | HOC | The return-leg wrapper — see *Concepts* |
+| `DispatcherProps`, `TDispatcherHOC`, `DispatcherRenderer`, `DispatcherRendererProps` | type | Dispatcher contract |
+| `DEFAULT_ALIAS` | const | `'auth'` — the service alias and the client guard alias |
+| `AUTH_RESOURCE`, `USER_ID` | const | `'auth'` resource and `'user'` record id holding the token |
+| `DEFAULT_ENTITY` | const | `'owlmeans'` |
+| `AuthServiceAppend`, `ClientAuthRecord`, `ClientAuthResource` | type | `context.auth()` and the stored record |
+
+### `@owlmeans/client-auth/manager`
+
+Importing it registers `basic-ed25519`, `re-captcha` and `wallet-consumer`, plus
+`pluginMethodSource`, by side effect.
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `plugins`, `authPluginHelper` (`registerAuthPlugin`, `getAuthPlugin`, `listAuthPlugins`), `AuthPluginHelper` | registry | The module-global authentication-plugin registry |
+| `AuthenticationHOC(Renderer?, type?)` | HOC | The authentication screen hosting a plugin |
+| `AuthenticationProps`, `TAuthenticationHOC` | type | Screen props (`type?`, `callback?`, `source?`) |
+| `makeControl(context, callback?)` | function | The control a plugin drives: `requestAllowence`, `authenticate`, `persist` / `restore` / `hasPersistentState` / `cleanUpState`, `setError`, `flow` |
+| `AuthenticationControl`, `AuthenticationControlState` | type | Control shape and the state persisted across a provider redirect |
+| `AuthenticationRenderer`, `AuthenticationRendererProps`, `ClientAuthType`, `ClientAuthenticationMethod`, `AuthenticationCallback` | type | Rendering contract |
+| `TunnelConsumer`, `TunnelAuthenticationProps`, `TunnelAuthCallback` | component, type | Wallet-tunnel consumer screen |
+| `AuthenCredError` | class | The entered credential cannot be used |
+| `CONTROL_STATE_ID` | const | Resource id of the persisted control state |
+
+### `@owlmeans/client-auth/manager/entrypoints`
 
-Returns the current `Auth` object from the context, or `null` if not authenticated.
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `entrypoints` | const | The authentication manager app's bindings: `authen`, `init`, `authenticate`, `rely`, `client`, `login`, the `loginDefault` / `loginTyped` screens and the dispatcher |
 
-### `setupExternalAuthentication(ctx, opts?)`
+### `@owlmeans/client-auth/manager/plugins`
 
-Configures the context to redirect to an external identity provider for authentication.
+The plugin-authoring surface, with no registration side effect.
 
-### `modules`
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `AuthenticationPlugin` | type | `type`, `Implementation`, `Renderer?`, `requiresRenderer?`, `method?`, `authenticate` / `beforeAuthenticate` / `afterAuthenticate` |
+| `PluginImplemnetation` (sic) | type | `(Renderer?) => FC<AuthenticationRendererProps>` |
+| `AuthMethodMeta` | type | `id`, `label`, `i18nKey`, `icon`, `order`, `emphasis`, `restricted`, `hidden`, `available(ctx)` |
+| `plugins`, `authPluginHelper`, `AuthPluginHelper` | registry | Same registry as `./manager` |
+| `pluginMethodSource` | const | The `LoginMethodSource` that offers registered plugins |
+| `createWalletFacade`, `PinSchema`, `PinForm`, `TunnelAuthenticationRenderer`, `TunnelAuthenticationRendererProps` | function, const, type | Wallet-tunnel helpers |
+| `ed25519BasicUIPlugin`, `reCaptchaPlugin`, `tunnelConsumerUIPlugin` | const | Shipped plugin objects |
 
-Pre-built `ClientModule[]` for the auth flow (mirrors `@owlmeans/auth-common`'s modules with client route models).
+### `@owlmeans/client-auth/login`
 
-### `DEFAULT_ALIAS`
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `appendLogin(ctx)` | function | Register the host; expose `context.login()` |
+| `makeLoginService(alias?)`, `ensureLoginService(ctx)` | function | The lazy login service, and the idempotent getter a plugin package calls first |
+| `LoginService`, `LoginServiceAppend`, `LoginContext` | type | `registerPlugin`, `registerPrecondition`, `registerMethodSource`, `registerScreen`, `screen`, `env`, and the `enter` / `begin` / `authorize` / `complete` / `resume` / `logout` / `logoutComplete` / `adopt` / `revoke` facade |
+| `LoginPlugin`, `LoginEnv`, `LoginRequest`, `LogoutRequest`, `LoginPrecondition` | type | Plugin contract |
+| `LoginOutcome`, `LoginIntent` | enum | Stage results; login or logout surrogate |
+| `useLogin(target?)` | hook | `[dispatcherPath, onLogIn]` |
+| `useLogout(target?)` | hook | `onLogOut` |
+| `loginMethodsHelper` — `.registerMethodSource`, `.listMethodSources`, `.resolveLoginMethods(ctx, cfg?, extra?)`, `.primaryLoginMethod(methods)`; `LoginMethodsHelper` | helper, type | Global method sources and resolution |
+| `LoginMethod`, `LoginMethodSource`, `LoginMethodContext` | type | Method contract |
+| `loginTermsHelper` — `.resolveTerms(cfg?)`, `.termsAccepted(resolved)`, `.acceptTerms(resolved, accepted)`; `LoginTermsHelper`, `ResolvedTerms` | helper, type | Terms confirmation, stored in `localStorage` against a version derived from the URLs |
+| `loginTermsHelper` — `.termsLabelResolver(translate, locale)`, `.termsAcceptanceOf(resolved, locale?)`; `LoginTermsAcceptance`, `TermsAcceptanceRef` | helper, type | The one document-label resolver every terms renderer shares; the wire shape a sign-in-time acceptance sends the server (structurally `@owlmeans/marketing-consent`'s `TermsAcceptance`, no dependency on it) |
+| `loginTermsHelper.termsDeferred(ctx)` | helper | True once a registered AND bound `LoginStep` declares `confirmsTerms` — the sign-in screen then renders no checkbox and blocks nothing, because the confirmation lives on that step instead |
+| `resolveCredit(cfg?, brand?, service?)`, `ResolvedCredit` | function, type | The credit and copyright line |
+| `FallbackLoginScreen`, `LoginScreenProps`, `LoginScreenComponent` | component, type | The plain screen used when no UI family registered one |
+| `surrogatePath(ctx, target)`, `SurrogateTarget` | function, type | Where a surrogate window opens; `null` on an entrypoint list without the surrogate route |
+| `loginResumeHelper` — `.resumeAction(outcome)`, `.loginAttemptError(outcome)`; `LoginResumeHelper`, `ResumeAction` | helper, enum | The shared readings of a `resume` outcome and of a finished attempt |
+| `enterOidcAuthorization(model)` | function | Move a flow to the step that can authorize; idempotent |
+| `loginTokenOf(ctx)` — `.adoptToken(token)`, `.revokeToken()`; `makeLoginTokenHelper`, `LoginTokenHelper` | helper | The single adoption and de-adoption paths |
+| `loginLandingOf(ctx)` — `.landAfterLogin(opts?)`, `.continueLogin(opts?)`, `.landingUrl(landing)`; `makeLoginLandingHelper`, `LoginLandingHelper`, `useContinueLogin()` | helper, hook | Where a finished sign-in lands: pending steps, landing hooks, a suspended flow, else the fallback |
+| `loginEnvHelper` — `isEmbedded`, `isSurrogate`, `markSurrogate`, `clearSurrogate`, `defaultLoginEnv`; `LoginEnvHelper` | helper | Environment probes behind `LoginEnv` |
+| `LOGIN_SERVICE`, `DEFAULT_ALIAS`, `DEFAULT_LOGIN_PRIORITY`, `DEFAULT_METHOD_ORDER`, `LOGIN_SURROGATE_NAME`, `LOGIN_TOKEN_MESSAGE`, `LOGIN_LOGOUT_MESSAGE`, `LOGIN_SURROGATE_MARKER`, `LOGIN_SURROGATE_FEATURES`, `LOGIN_WATCH_INTERVAL`, `LOGIN_INTENT_QUERY`, `LOGIN_NEXT_QUERY`, `LOGIN_METHOD_QUERY`, `LOGIN_TERMS_STORAGE` | const | Service alias, ordering defaults and cross-document wire values |
 
-Auth service alias: `'auth'`.
+Importing `./login` also registers the `login` strings of the `auth` library namespace in all
+seven supported languages.
 
-## Product-Viable Integration Notes
+## Common pitfalls
 
-- The manager web app imports `DEFAULT_ALIAS` from this package as the client-side guard alias.
-- `@owlmeans/web-oidc-rp/auth/plugins` is imported for side effects to register the `OIDC_CLIENT_AUTH` and `GOOGLE_CLIENT_AUTH` plugins.
-- Redirect plugins persist auth control state before leaving the app and restore it before submitting provider query params as `AuthCredentials`.
-- After login, the browser stores a normal OwlMeans bearer token; product authorization is enforced by server gates and handler checks.
+- **Keep sign-in handlers synchronous.** `useLogin` and `useLogout` handlers await nothing before
+  delegating. Wrapping them in an `async` handler that awaits first makes the popup blocker eat the
+  surrogate window. The same rule binds a plugin's `begin` / `logout`, a method's `start` and every
+  precondition.
+- **Never start login from an effect.** Without a user gesture the window is blocked. Render a
+  control and let the person click.
+- **Adopt and drop tokens only through the auth service or `loginTokenOf(ctx).adoptToken` / `.revokeToken`.**
+  Hand-written access to `AUTH_RESOURCE` drifts from the envelope decoding beside it.
+- **Import names from the right subpath.** The plugin contract (`AuthenticationPlugin`,
+  `AuthMethodMeta`, `pluginMethodSource`, tunnel helpers) resolves only through
+  `./manager/plugins`. Rendering types and the registry resolve through `./manager`. Importing
+  `./login` registers no authentication plugin.
+- **Gate operator methods with `method.restricted`,** so the configuration has to name them. Gate
+  dev-only methods on `cfg.debug.supervisor`, never `cfg.debug.all`.
+- **Declare `requiresRenderer`** on a plugin whose `Implementation` cannot render without a UI
+  package's `Renderer`. Otherwise the screen offers a button that crashes the page it opens.
+- **Call `enterOidcAuthorization(model)` before every `authenticate`** in an OIDC flow, rather than
+  re-deriving the transition.
+- **Authorization stays server-side.** The browser ends up holding an ordinary OwlMeans bearer token
+  whichever provider issued it. Product checks live in entrypoint gates and handlers, never in
+  client-only state.
+- **The organization on the wire is its `entitySlug`.** Read it with `authHelper.entitySlugOf` from
+  `@owlmeans/auth`; the stable `entityId` never reaches the browser.
+- **Overrides of the `login` strings cover all seven languages** (`en`, `pl`, `ru`, `be`, `uk`,
+  `es`, `de`).
 
-## Related Packages
+## Related packages
 
-- [`@owlmeans/auth`](../auth) — `Auth` type returned by `useSelfAuth`
-- [`@owlmeans/auth-common`](../auth-common) — auth module route definitions
-- [`@owlmeans/server-auth`](../server-auth) — server-side counterpart
+- [`@owlmeans/auth`](../auth) — `Auth`, aliases, `authHelper.entitySlugOf`, auth errors
+- [`@owlmeans/auth-common`](../auth-common) — `authProtocols`, `authMiddleware`, guard aliases
+- [`@owlmeans/web-client`](../web-client) — appends the auth service and login host; ships the dispatcher and login plugins
+- [`@owlmeans/web-panel`](../web-panel) — the shadcn sign-in screen (`appendLoginScreen`)
+- [`@owlmeans/client-panel`](../client-panel) — headless login-method and terms models
+- [`@owlmeans/web-oidc-rp`](../web-oidc-rp) — OIDC relying party and its method source
+- [`@owlmeans/web-auth`](../web-auth) — supervisor (PK) login plugin
+- [`@owlmeans/client-socket`](../client-socket) — the socket hook `useWs` wraps
+- [`@owlmeans/server-auth`](../server-auth) — the server-side counterpart
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -76,7 +322,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.53
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/client-auth",
-  "version": "0.1.18-rc.6",
-  "generatedAt": "2026-08-18T14:48:00.497Z",
+  "version": "0.1.18-rc.61",
+  "generatedAt": "2026-10-09T11:30:42.733Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/client-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client-auth
-description: How to use @owlmeans/client-auth — client-side auth manager and UI components, setupExternalAuthentication() to wire OAuth/OIDC flows. Auto-invoked when importing client-auth helpers or registering external authentication.
+description: How to use @owlmeans/client-auth — the browser side of OwlMeans authentication. Root exports the auth service, the shared client entrypoints and the dispatcher HOC; ./manager holds the authentication screen, its control and the plugin registry; ./manager/plugins holds the authentication-plugin contract a plugin package writes against; ./login holds the login-plugin host, the sign-in method registry, the terms confirmation and the useLogin/useLogout hooks. Auto-invoked when importing client-auth helpers, registering an authentication plugin, or wiring a sign-in control.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,41 +8,190 @@ user-invocable: false
 # @owlmeans/client-auth
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-auth": "^0.1.18-rc.6"` in `dependencies`
+**Install:** `"@owlmeans/client-auth": "^0.1.18-rc.61"` in `dependencies`
 
-## Key Exports
+Five subpaths, five jobs:
+
+| Subpath | Job |
+|---------|-----|
+| `.` | The client `AuthService`, the shared auth entrypoints, and the dispatcher HOC |
+| `./manager` | The registry's four names plus the authentication screen, control and error — *how* a user proves identity. Importing it registers the three shipped browser plugins and `pluginMethodSource` by side effect |
+| `./manager/entrypoints` | The manager application's own front-end entrypoint bindings |
+| `./manager/plugins` | The plugin-authoring surface, and a superset of the registry: the `AuthenticationPlugin` contract, `pluginMethodSource`, the wallet-tunnel helpers and the shipped plugin objects — with no registration side effect |
+| `./login` | The **login**-plugin host — *where* the authorization round trip runs, and which method a person picks |
+
+A plugin package imports from both, and the split is fixed: `AuthenticationPlugin`,
+`AuthMethodMeta`, `pluginMethodSource`, `PinSchema`, `createWalletFacade`,
+`TunnelAuthenticationRenderer` and the shipped plugin objects resolve **only** through
+`./manager/plugins`; the registry (`plugins`, `registerAuthPlugin`, …) and the rendering types
+(`AuthenticationRenderer`, `AuthenticationControl`, `ClientAuthType`, `AuthenticationHOC`) resolve
+through `./manager`. Importing the contract from `./manager` gets an unresolvable name.
+
+`./manager/plugins` and `./login` answer different questions and are separate registries. Do not
+conflate them.
+
+## Key Exports — root
 
 | Export | Description |
 |--------|-------------|
-| `setupExternalAuthentication(alias)` | Register OAuth/OIDC external auth flow module |
-| Auth components | Login UI primitives |
-| Auth service | Client-side auth manager service |
-| Modules | Auth module declarations |
-| Constants | Auth aliases (re-exports `AUTH_API`) |
+| `makeAuthService(alias?)` | The client `AuthService` — `authenticate(token)`, `update(token)`, `authenticated()`, `user()`, `store()`. Decodes the bearer envelope and persists the record |
+| `appendAuthService(ctx, alias?)` | Register it, register `authMiddleware`, and expose `context.auth()` |
+| `setupExternalAuthentication(service)` | Point the `CAUTHEN_FLOW_ENTER` entrypoint at a service, so an external provider can redirect into this app |
+| `entrypoints` | The shared auth entrypoint list with `DISPATCHER_AUTHEN` bound |
+| `DEFAULT_ALIAS` | `'auth'` — the client-side counterpart of `DEFAULT_GUARD` |
+| `AUTH_RESOURCE` | `'auth'` — the resource the token record is stored in |
+| `USER_ID` | `'user'` — the id of that single record |
+| `DEFAULT_ENTITY` | `'owlmeans'` |
+| `DispatcherHOC` | The return-leg HOC. It wraps a `DispatcherRenderer`, hands it `provideToken(token, query)` and `navigate()`, adopts the supplied token through the auth service, and strips `AUTH_QUERY` before navigating on. Reading the return-leg query is the renderer's job — `@owlmeans/web-client` reads `AUTH_QUERY`, `@owlmeans/web-oidc-rp` also reads `OIDC_ERROR_QUERY` and forwards the remaining params |
+| `DispatcherProps`, `TDispatcherHOC`, `DispatcherRenderer`, `DispatcherRendererProps` | Dispatcher types |
+| `useWs(entrypoint, request?, options?)` | A socket hook that attaches the current token as the `AUTH_QUERY` param and refreshes it on every reconnect attempt (via `WsOptions.beforeConnect`), unless the request already carried its own token — in which case that stays untouched across reconnects too. `options` passes straight through to `@owlmeans/client-socket`'s `useWs`, so `{ reconnect: false }` still opts a stateful one-shot handshake out of retries (see `manager/plugins/tunnel-consumer.tsx`) |
+| `useSelfAuth(force?)` | Whether this context is authenticated; navigates to `DISPATCHER` when it is not and `force` |
+| `AuthServiceAppend`, `ClientAuthRecord`, `ClientAuthResource` | Types |
+
+## `./manager` — the authentication screen and the registry
+
+| Export | Description |
+|--------|-------------|
+| `plugins`, `authPluginHelper` → `.registerAuthPlugin`, `.getAuthPlugin`, `.listAuthPlugins` | The module-global registry |
+| `AuthenticationHOC`, `AuthenticationProps`, `TAuthenticationHOC` | The screen that hosts a plugin's implementation |
+| `makeControl`, `AuthenticationControl`, `AuthenticationControlState` | The control a plugin drives: `requestAllowence`, `authenticate`, and the state it persists across a provider redirect |
+| `AuthenticationRenderer`, `AuthenticationRendererProps`, `ClientAuthType`, `ClientAuthenticationMethod`, `AuthenticationCallback` | Rendering contract |
+| `TunnelConsumer`, `TunnelAuthenticationProps`, `TunnelAuthCallback` | The wallet-tunnel consumer screen |
+| `AuthenCredError` | Thrown when the entered credential cannot be used |
+
+## `./manager/plugins` — the authentication-plugin contract
+
+| Export | Description |
+|--------|-------------|
+| `AuthenticationPlugin` | `type`, `Implementation`, optional `Renderer`, `requiresRenderer?`, `method?` and the `authenticate` / `beforeAuthenticate` / `afterAuthenticate` hooks |
+| `PluginImplemnetation` (sic) | `(Renderer?) => FC<AuthenticationRendererProps>` — the shape of `Implementation` |
+| `AuthMethodMeta` | How the plugin presents itself as a sign-in method — see `login-methods` |
+| `plugins`, `authPluginHelper` | The same registry as `./manager` |
+| `pluginMethodSource` | The `LoginMethodSource` that turns registered plugins into offerable methods |
+| `createWalletFacade`, `PinSchema`, `PinForm`, `TunnelAuthenticationRenderer`, `TunnelAuthenticationRendererProps` | Wallet-tunnel helpers a consumer plugin builds on |
+| `ed25519BasicUIPlugin`, `reCaptchaPlugin`, `tunnelConsumerUIPlugin` | The shipped plugin objects |
+
+Shipped plugins register themselves by side effect: `basic-ed25519`, `re-captcha` and
+`wallet-consumer` when `@owlmeans/client-auth/manager` is imported, OIDC and Google from
+`@owlmeans/web-oidc-rp/auth/plugins`, the PK supervisor from `@owlmeans/web-auth`.
 
-## Subpath Exports
+## `./login` — the login-plugin host
 
-- `./manager` — client-side auth manager
-- `./manager/modules` — manager module declarations
-- `./manager/plugins` — pluggable token providers
+An `AuthenticationPlugin` answers how a credential is proven; a `LoginPlugin` answers in which
+browsing context the round trip can complete at all.
+
+| Export | Description |
+|--------|-------------|
+| `appendLogin(ctx)` | Register the host and expose it as `context.login()` |
+| `makeLoginService(alias?)`, `ensureLoginService(ctx)` | The host itself — a **lazy** service, so `makeContext` can reach it at the Loading stage — and the idempotent getter a plugin package calls before `registerPlugin` |
+| `LoginPlugin`, `LoginEnv`, `LoginRequest`, `LogoutRequest`, `LoginOutcome`, `LoginIntent`, `LoginService`, `LoginContext`, `LoginPrecondition` | The contract |
+| `loginMethodsHelper` → `.registerMethodSource`, `.listMethodSources`, `.resolveLoginMethods`, `.primaryLoginMethod` | Which sign-in methods are offered — see `login-methods` |
+| `LoginMethod`, `LoginMethodSource`, `LoginMethodContext` | Method types |
+| `loginLandingOf(ctx)` → `.landAfterLogin(opts?)`, `.continueLogin(opts?)`, `.landingUrl(landing)`; `useContinueLogin()` | The post-login landing decision (`src/login/land.ts`) — see `login-plugins`. `landAfterLogin` runs due landing hooks then delegates to `continueLogin`, which walks pending `LoginStep`s, then `flowLandingOf(ctx).resumeSuspendedFlow`, then `LandOptions.fallback ?? { alias: HOME }`; `landingUrl` builds the absolute URL a plugin's own `window.location.href` needs; `useContinueLogin()` is what a step's own screen calls once satisfied |
+| `LoginStep`, `LoginLanding`, `LoginLandingHook`, `LandOptions`, `LoginLandingParams` | Landing-seam types. `registerStep`/`steps`/`onLanded`/`landingHooks` on `LoginService` are the same replace-by-alias, priority-sorted registries as `registerPlugin`. `LoginStep` also carries `confirmsTerms?: boolean` (this step is where the Terms confirmation lives — see `loginTermsHelper.termsDeferred` below) and `required?: boolean` (a throw/timeout in `pending` reads as PENDING, not "not pending" — see `login-plugins`) |
+| `LOGIN_STEP_TIMEOUT`, `LOGIN_LANDED_STORAGE` | A step's `pending`/a hook's `landed` is bounded by the former; the latter is where the last-landed token is recorded (the raw string, never a digest) |
+| `loginTermsHelper` → `.resolveTerms`, `.termsAccepted`, `.acceptTerms`, `.termsSentence`, `ResolvedTerms`, `ResolvedTermsDocument`, `TermsSentencePart` | The confirmation. `resolveTerms` produces `documents` (what the checkbox agrees to: terms, then billing/product/custom when configured) and `notices` (what is only disclosed: privacy, plus cookies per its own inclusion rule) — see the terms-confirmation section of `login-methods`. The extra `LoginTermsConfig` fields (`billing`, `product`, `documents`, `revisions`, `showRevision`, `localizedHrefs`) are added by module augmentation in `src/login/terms-config.ts`, never by editing `@owlmeans/config` — importing anything from `@owlmeans/client-auth/login` pulls it in |
+| `loginTermsHelper.termsLabelResolver(translate, locale)`, `loginTermsHelper.termsAcceptanceOf(resolved, locale?)`, `TermsAcceptanceRef` | The ONE document-label resolver and ONE wire-shape builder every terms renderer/recorder shares (`FallbackLoginScreen`, `web-panel`'s `LoginTerms`, `web-marketing-consent`'s Terms box and `termsRecorder`) — no more hand-kept duplicate `DEFAULT_LABEL`/`resolveLabelFor` per package. `termsAcceptanceOf` keeps only `{key, href, revisedAt}` per document — structurally `@owlmeans/marketing-consent`'s `TermsAcceptance`, with no dependency on that package |
+| `loginTermsHelper.termsDeferred(ctx)` | True once a registered AND BOUND `LoginStep` declares `confirmsTerms` — see the "Deferring the confirmation" section of `login-methods`. Reads `ctx.hasService`/`.hasEntrypoint` directly, never `ensureLoginService` (which has the side effect of registering an empty host) |
+| `resolveCredit`, `ResolvedCredit` | The credit and copyright line |
+| `FallbackLoginScreen`, `LoginScreenProps` (now also carries `locale?: string`, for `Intl.ListFormat` and a custom document's locale-keyed label), `LoginScreenComponent` | The plain sign-in screen a relying party renders when no UI family registered one |
+| `surrogatePath(ctx, target)`, `SurrogateTarget` | Where a surrogate login window opens; `null` on an older entrypoint list |
+| `loginResumeHelper.resumeAction(outcome)`, `ResumeAction`, `loginResumeHelper.loginAttemptError(outcome)` | The one reading of a `resume` outcome, and the one reading of a finished attempt |
+| `registerNotifier(notifier)` (on `LoginService`), `LoginNotifier` | Surfaces a `begin`/`logout` outcome that has no inline screen to render it on — e.g. a toast on `LoginOutcome.Blocked` for a header "Log in"/"Log out" control. `web-panel`'s `appendLoginScreen` registers a default; unregistered, it is silence |
+| `enterOidcAuthorization(model)` | Move a flow to the step that can authorize — idempotent, call it before every `authenticate` |
+| `loginTokenOf(ctx).adoptToken(token)`, `.revokeToken()` | The single adoption and de-adoption paths |
+| `useLogin(target?)`, `useLogout(target?)` | Wiring for a sign-in / sign-out control. `useLogin`'s `target` is the screen to land on AFTER sign-in (parked, never navigated to first); `useLogout`'s is where the document goes once the session is gone |
+| `loginStartOf(ctx).startLogin({ url, target?, go })`, `LoginStart` | The React-free decision behind `useLogin` (`src/login/start.ts`): a target with a session already held goes straight there; otherwise `begin` with the target and a continuation to `DISPATCHER` |
+| `loginEnvHelper` → `.isEmbedded`, `.isSurrogate`, `.markSurrogate`, `.clearSurrogate`, `.defaultLoginEnv` | Environment probes the host builds `LoginEnv` from |
+| `LOGIN_SERVICE`, `LOGIN_SURROGATE_NAME`, `LOGIN_TOKEN_MESSAGE`, `LOGIN_LOGOUT_MESSAGE`, `LOGIN_SURROGATE_MARKER`, `LOGIN_SURROGATE_WIDTH`, `LOGIN_SURROGATE_HEIGHT`, `LOGIN_WATCH_INTERVAL`, `LOGIN_INTENT_QUERY`, `LOGIN_NEXT_QUERY`, `LOGIN_METHOD_QUERY`, `LOGIN_TERMS_STORAGE`, `LOGIN_TARGET_TTL`, `DEFAULT_LOGIN_PRIORITY`, `DEFAULT_METHOD_ORDER` | Aliases and the fixed cross-document wire values. `LOGIN_SURROGATE_FEATURES` also still exports (deprecated, never centered) — `@owlmeans/web-client`'s `centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT)` is what the surrogate plugin actually opens the window with |
+
+```typescript
+import { useLogin, useLogout } from '@owlmeans/client-auth/login'
+
+const [loginPath, onLogIn] = useLogin()
+const onLogOut = useLogout()
+```
+
+Both handlers are deliberately **not** async and await nothing before delegating — a window opened
+after the user gesture has finished being handled is eaten by the popup blocker. Each resolves its
+entrypoint **inside** the hook, never at module scope — `DISPATCHER` for `useLogin`, the surrogate
+path for `useLogout`. A module body runs before `registerEntrypoints`, so `useLogin`'s lookup at
+top level throws `Entrypoint dispatcher not found` during import, taking the whole render down.
+
+`useLogin(target)` signs in FIRST and lands on `target` after, in an ordinary tab (redirect plugin)
+and in a framed application (surrogate popup) alike, with every pending post-sign-in step run on the
+way. Its `navigate` continuation is ALWAYS `DISPATCHER` — never the target, because a guarded screen
+reached before sign-in renders signed out. The target travels as `LoginRequest.target`: the facade's
+`begin`, past the preconditions, parks it with `flowLandingOf(ctx).suspendLanding`
+(`@owlmeans/client-flow`, the `RESUME_FLOW` record its `resumeSuspendedFlow` reads, expiring after
+`LOGIN_TARGET_TTL`) — the write is started, never awaited before the plugin, so a popup still opens
+inside the gesture — and holds the continuation until the write has landed. The dispatcher's
+`landAfterLogin` (landing hooks → pending steps such as a consent screen → the parked target) then
+ends on it. An attempt that signs nobody in (`Blocked`, `Failed`, `Gesture`) discards the parked
+target; a refused precondition never parks it. A session already held (the auth service's in-memory
+`token`) goes straight to the target. Without a target, `useLogin()` is the plain sign-in to the
+ordinary landing. A caller of `login().begin` that passes a `target` without a `navigate` leaves the
+document at once, so its parked target is best-effort.
+
+`useLogout` sends a continuation only when a target is given. Omitting it does not leave the session
+behind: the token is revoked either way, and the plugin decides what the document does with no
+continuation to run — `@owlmeans/web-client`'s redirect plugin reloads the page, because cached auth
+reads only forget a session when the application is rebuilt. `useLogin` returns `[path, handler]`
+(the path is the dispatcher's, with or without a target) and `useLogout` a bare handler — a logout
+control has no address to point at.
+
+Plugin selection, the shipped browser flows and the full invariant list: the `login-plugins` skill.
 
 ## Usage
 
 ```typescript
-import { setupExternalAuthentication } from '@owlmeans/client-auth'
+import { appendAuthService, setupExternalAuthentication, DEFAULT_ALIAS } from '@owlmeans/client-auth'
+import { appendLogin } from '@owlmeans/client-auth/login'
 
-setupExternalAuthentication(AUTH_WEB) // alias of the web auth service
+// in makeContext:
+appendAuthService(context)             // registers under DEFAULT_ALIAS ('auth')
+appendLogin(context)
+setupExternalAuthentication(MY_WEB_SERVICE)   // the service alias the provider redirects into
 ```
 
-## Product-Viable Usage Notes
+`@owlmeans/web-client`'s own `makeContext` already appends the auth service and the login host, so
+a web application only calls these when it builds its context by hand.
+
+## Rules
 
-- The manager web app imports `DEFAULT_ALIAS` from `@owlmeans/client-auth` as the client-side equivalent of `DEFAULT_GUARD`.
-- It imports `@owlmeans/web-oidc-rp/auth/plugins` for side effects; that registers OIDC and Google authentication plugins in the client auth manager.
-- During Google/OIDC redirects, plugins persist the client auth control state, restore it on return, then submit `AuthCredentials` to the server auth flow.
-- The browser receives and stores a normal OwlMeans bearer token. Product authorization remains server-side through module gates and handler checks, not through client-only state.
+- An application's translated legal destinations are opt-in `login.terms.localizedHrefs`, keyed by
+  document/notice key, then locale. `loginTermsHelper.termsHrefOf(doc, locale?)` selects the exact
+  configured locale, then its base language, then `doc.href`. `termsSentence` and `termsAcceptanceOf`
+  share that resolver: pass the same live UI language to both. The canonical href and revisions still
+  determine the agreement digest; translations alone never ask for a new acceptance. Supply known
+  published destinations, never infer another application's URL layout. Omitted maps preserve defaults.
+- The bearer token lives in the `AUTH_RESOURCE` resource under the single id `USER_ID`. Read and
+  write it through the auth service or through `loginTokenOf(ctx).adoptToken` / `.revokeToken`;
+  hand-written storage access drifts from the envelope decoding that happens beside it.
+- A plugin that persists state across a provider redirect drives the control's own
+  `persist()` / `restore()` / `hasPersistentState()` / `cleanUpState()`. They keep the type, stage
+  and allowance in the `FLOW_STATE` resource under an id this package owns and does not export —
+  restore before submitting the credential, and clean up after.
+- After a sign-in, `DispatcherHOC.navigate` calls `loginLandingOf(ctx).landAfterLogin` — a pending
+  `LoginStep`, else a landing suspended in `@owlmeans/client-flow`
+  (`flowLandingOf(ctx).resumeSuspendedFlow`, one-shot, an entrypoint alias plus its query — parked
+  by a flow's `.suspendFlow` or by `useLogin(target)`), else `HOME` — read BEFORE `alias` is
+  defaulted to `HOME`. Login plugins that navigate on their own do the same — see `login-plugins`.
+- A control that leads to a screen through sign-in is `useLogin(target)`. Never navigate to a guarded
+  screen to start a sign-in, and never hand a plugin a continuation that goes anywhere but the
+  dispatcher: the landing is the dispatcher's decision.
+- The browser ends up holding an ordinary OwlMeans bearer token whichever provider issued the
+  login. Product authorization stays server-side, in entrypoint gates and handler checks — never in
+  client-only state.
+- The organization entity a token names is its `entitySlug`, the renameable public name. Read it
+  with `authHelper.entitySlugOf` from `@owlmeans/auth`; the stable `entityId` never reaches the
+  browser.
 
 ## Depends On
 
-- `@owlmeans/auth`, `@owlmeans/auth-common`
-- `@owlmeans/client-context`, `@owlmeans/client-entrypoint`
+- `@owlmeans/auth`, `@owlmeans/auth-common` — types, aliases, `authMiddleware`
+- `@owlmeans/client`, `@owlmeans/client-context`, `@owlmeans/client-entrypoint`, `@owlmeans/client-socket`
+- `@owlmeans/config` — the login screen, terms and credit configuration
+- `@owlmeans/basic-envelope` — decoding the bearer envelope
 - `react` (peer)
+- `ajv` (peer) — `PinSchema` is typed as `JSONSchemaType<PinForm>`

package/build/components/dispatcher/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA2B,cAAc,EAAE,MAAM,YAAY,CAAA;AAczE,eAAO,MAAM,aAAa,EAAE,cA4E3B,CAAA"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA2B,cAAc,EAAE,MAAM,YAAY,CAAA;AAgBzE,eAAO,MAAM,aAAa,EAAE,cAqG3B,CAAA"}