@owlmeans/client-auth 0.1.18-rc.9 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-auth",
-  "version": "0.1.18-rc.9",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -27,12 +27,12 @@
       "module": "./build/manager/index.js",
       "types": "./build/manager/index.d.ts"
     },
-    "./manager/modules": {
-      "import": "./build/manager/modules.js",
-      "require": "./build/manager/modules.js",
-      "default": "./build/manager/modules.js",
-      "module": "./build/manager/modules.js",
-      "types": "./build/manager/modules.d.ts"
+    "./manager/entrypoints": {
+      "import": "./build/manager/entrypoints.js",
+      "require": "./build/manager/entrypoints.js",
+      "default": "./build/manager/entrypoints.js",
+      "module": "./build/manager/entrypoints.js",
+      "types": "./build/manager/entrypoints.d.ts"
     },
     "./manager/plugins": {
       "import": "./build/manager/plugins/exports.js",
@@ -50,35 +50,38 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.6",
-    "@owlmeans/auth-common": "^0.1.18-rc.7",
-    "@owlmeans/basic-envelope": "^0.1.18-rc.7",
-    "@owlmeans/basic-keys": "^0.1.18-rc.7",
-    "@owlmeans/client": "^0.1.18-rc.8",
-    "@owlmeans/client-context": "^0.1.18-rc.7",
-    "@owlmeans/client-flow": "^0.1.18-rc.7",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.7",
-    "@owlmeans/client-resource": "^0.1.18-rc.7",
-    "@owlmeans/client-socket": "^0.1.18-rc.7",
-    "@owlmeans/context": "^0.1.18-rc.6",
-    "@owlmeans/did": "^0.1.18-rc.7",
-    "@owlmeans/error": "^0.1.18-rc.6",
-    "@owlmeans/flow": "^0.1.18-rc.7",
-    "@owlmeans/entrypoint": "^0.1.18-rc.7",
-    "@owlmeans/resource": "^0.1.18-rc.7",
-    "@owlmeans/socket": "^0.1.18-rc.6",
-    "@owlmeans/web-flow": "^0.1.18-rc.7",
-    "@scure/base": "^2.3.0"
+    "@owlmeans/auth": "^0.1.18",
+    "@owlmeans/auth-common": "^0.1.18",
+    "@owlmeans/basic-envelope": "^0.1.18",
+    "@owlmeans/basic-keys": "^0.1.18",
+    "@owlmeans/client": "^0.1.18",
+    "@owlmeans/client-context": "^0.1.18",
+    "@owlmeans/client-entrypoint": "^0.1.18",
+    "@owlmeans/client-flow": "^0.1.18",
+    "@owlmeans/client-resource": "^0.1.18",
+    "@owlmeans/client-socket": "^0.1.18",
+    "@owlmeans/config": "^0.1.18",
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/did": "^0.1.18",
+    "@owlmeans/entrypoint": "^0.1.18",
+    "@owlmeans/error": "^0.1.18",
+    "@owlmeans/flow": "^0.1.18",
+    "@owlmeans/i18n": "^0.1.18",
+    "@owlmeans/log": "^0.1.18",
+    "@owlmeans/resource": "^0.1.18",
+    "@owlmeans/socket": "^0.1.18",
+    "@owlmeans/web-flow": "^0.1.18",
+    "@scure/base": "^2.4.0"
   },
   "peerDependencies": {
     "ajv": "*",
     "react": "*"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-auth": "^0.1.18-rc.7",
-    "@types/bun": "^1.3.14",
-    "@types/react": "^19.2.17",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@owlmeans/test-auth": "^0.1.18",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/components/dispatcher/component.tsx

@@ -1,34 +1,61 @@
 import { useCallback, useEffect, useState } from 'react'
 import type { DispatcherRendererProps, TDispatcherHOC } from './types.js'
-import type { AuthToken } from '@owlmeans/auth'
 import { AUTH_QUERY, DISPATCHER } from '@owlmeans/auth'
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import { HOME } from '@owlmeans/context'
 import { DEFAULT_ALIAS, DEFAULT_ENTITY } from '../../consts.js'
 import type { AuthService } from '@owlmeans/auth-common'
 import { useNavigate } from '@owlmeans/client'
-import type { AbstractRequest } from '@owlmeans/entrypoint'
-import type { FlowService } from '@owlmeans/client-flow'
-import { DEFAULT_ALIAS as FLOW_SERVICE } from '@owlmeans/client-flow'
+import { type FlowService, DEFAULT_ALIAS as FLOW_SERVICE } from '@owlmeans/client-flow'
 import { FLOW_PLACEHOLDER, OidcAuthStep, STD_OIDC_FLOW } from '@owlmeans/flow'
 import { SERVICE_PARAM } from '@owlmeans/web-flow'
+import { loginLandingOf } from '../../login/land.js'
+import { logger } from '@owlmeans/log'
+import type { StateToken } from './types.local.js'
+
+const log = logger('client-auth:dispatcher')
 
 export const DispatcherHOC: TDispatcherHOC = Renderer => ({ context, params, alias, query, payload }) => {
   const [forwarding, setForwarding] = useState<StateToken | undefined>()
 
   const navigator = useNavigate()
   const navigate = useCallback(async () => {
-    alias = alias == null || alias === DISPATCHER ? HOME : alias
-    const module = context.module<ClientEntrypoint<string>>(alias)
-    if (alias === HOME) {
-      params = {}
-      query = {}
+    if (alias == null || alias === DISPATCHER) {
+      // A sign-in that started elsewhere — a device or authorization-code consent screen, most
+      // commonly — suspended itself here before leaving, or a registered step still has
+      // something to collect (a marketing-consent screen, say). `landAfterLogin` is the whole
+      // post-sign-in landing decision (steps, landing hooks, the suspended flow, then HOME) and
+      // takes priority over the ordinary HOME landing, resolved BEFORE `alias` is overwritten,
+      // because once it is `HOME` there is no way back to tell the cases apart.
+      const landing = await loginLandingOf(context).landAfterLogin()
+      if (landing.alias !== HOME) {
+        await navigator.navigate(
+          context.entrypoint<ClientEntrypoint<string>>(landing.alias),
+          { params: landing.params, query: landing.query }
+        )
+        return
+      }
+      alias = HOME
     } else {
+      // A concrete destination already exists (an OIDC `?code=` return, etc.) — a registered step
+      // still gets to interject, but `resumeSuspendedFlow` must not run a second time: this
+      // branch already has somewhere to go.
       query = { ...forwarding?.query, ...query }
       if (query != null && AUTH_QUERY in query) {
         delete query[AUTH_QUERY]
       }
+      const landing = await loginLandingOf(context).landAfterLogin(
+        { fallback: { alias, params, query }, resume: false }
+      )
+      await navigator.navigate(
+        context.entrypoint<ClientEntrypoint<string>>(landing.alias),
+        { params: landing.params, query: landing.query }
+      )
+      return
     }
+    const module = context.entrypoint<ClientEntrypoint<string>>(alias)
+    params = {}
+    query = {}
     await navigator.navigate(module, { params, query })
   }, [forwarding])
 
@@ -78,7 +105,7 @@ export const DispatcherHOC: TDispatcherHOC = Renderer => ({ context, params, ali
           return await navigate()
         }).catch((e: Error) => {
           // @TODO Show error on the component
-          console.error(e)
+          log.error('Authentication failed', e, { event: 'auth.refused' })
         })
       }
     }
@@ -91,7 +118,3 @@ export const DispatcherHOC: TDispatcherHOC = Renderer => ({ context, params, ali
   return <Renderer provideToken={provideToken} navigate={navigate} />
 }
 
-interface StateToken {
-  token: AuthToken
-  query?: AbstractRequest['params']
-}

package/src/components/dispatcher/types.local.ts

@@ -0,0 +1,7 @@
+import type { AuthToken } from '@owlmeans/auth'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+
+export interface StateToken {
+  token: AuthToken
+  query?: AbstractRequest['params']
+}

package/src/entrypoints.ts

@@ -0,0 +1,10 @@
+
+import { bind, bindScreen, stab } from '@owlmeans/client-entrypoint'
+import { authProtocols } from '@owlmeans/auth-common'
+
+/** Browser entrypoints for the authentication protocols every client may call. */
+export const entrypoints = [bind(authProtocols.dispatcherAuthenticate)]
+
+/** Bind the external-authentication screen to one explicitly selected service. */
+export const bindExternalAuthentication = (service: string) =>
+  bindScreen(authProtocols.flowEnter, stab, { routeOptions: { overrides: { service } } })

package/src/helper.ts

@@ -1,18 +1,22 @@
 import { useContext, useNavigate } from '@owlmeans/client'
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
-import { provideRequest } from '@owlmeans/client-entrypoint'
 import { useWs as useWebSocket } from '@owlmeans/client-socket'
+import type { WsOptions } from '@owlmeans/client-socket'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
 import type { AuthServiceAppend } from './types.js'
 import { useEffect, useMemo, useState } from 'react'
 import type { ClientContext } from '@owlmeans/client-context'
 import { AUTH_QUERY, DISPATCHER } from '@owlmeans/auth'
+import { logger } from '@owlmeans/log'
+import { clientRequestHelper } from '@owlmeans/client-entrypoint'
+
+const log = logger('client-auth')
 // import { useFlow } from '@owlmeans/web-flow'
 // import { DEFAULT_ENTITY } from './consts.js'
 // import { OidcAuthStep } from '@owlmeans/flow'
 
 export const useWs = (
-  module: string | ClientEntrypoint<any>, _request?: Partial<AbstractRequest<any>>
+  module: string | ClientEntrypoint<any>, _request?: Partial<AbstractRequest<any>>, options?: WsOptions
 ) => {
   const ctx = useContext() as unknown as AuthServiceAppend & ClientContext
 
@@ -20,9 +24,13 @@ export const useWs = (
     () => typeof module === 'string' ? ctx.entrypoint<ClientEntrypoint>(module) : module, [module]
   )
 
+  // Captured before the token is filled in below, so a caller who supplied their own token
+  // keeps full control of it across a reconnect too — `beforeConnect` only refreshes ours.
+  const callerSuppliedToken = _request?.query?.[AUTH_QUERY] != null
+
   const request = useMemo(() => {
     if (_request == null) {
-      _request = provideRequest(mod.getAlias(), mod.getPath())
+      _request = clientRequestHelper.provideRequest(mod.alias, mod.path())
     }
     try {
       if (_request?.query?.[AUTH_QUERY] == null) {
@@ -32,13 +40,31 @@ export const useWs = (
         _request.query[AUTH_QUERY] = ctx.auth().token
       }
     } catch (e) {
-      console.error(e)
+      log.warn('Socket auth token not attached', e)
     }
 
     return _request
   }, [_request])
 
-  return useWebSocket(module, request)
+  const wsOptions = useMemo<WsOptions>(() => ({
+    ...options,
+    beforeConnect: async req => {
+      // A reconnect can land minutes after the socket first opened — refresh the bearer token
+      // on every attempt rather than trust the one `request` was built with, or a token rotated
+      // in between reopens the socket with a stale one the guard then rejects.
+      if (!callerSuppliedToken) {
+        try {
+          req.query ??= {}
+          req.query[AUTH_QUERY] = ctx.auth().token
+        } catch (e) {
+          log.warn('Socket auth token not refreshed', e)
+        }
+      }
+      await options?.beforeConnect?.(req)
+    }
+  }), [options, callerSuppliedToken])
+
+  return useWebSocket(module, request, wsOptions)
 }
 
 export const useSelfAuth = (force: boolean = true/*, entity: string = DEFAULT_ENTITY*/) => {

package/src/index.ts

@@ -3,5 +3,5 @@ export * from './components/index.js'
 export type * from './types.js'
 export * from './service.js'
 export * from './consts.js'
-export * from './modules.js'
+export * from './entrypoints.js'
 export * from './helper.js'

package/src/login/adopt/types.ts

@@ -0,0 +1,25 @@
+/** The two paths a context's authentication changes by: a token adopted, a token dropped. */
+export interface LoginTokenHelper {
+  /**
+   * The one path an issued bearer token becomes this context's authentication.
+   *
+   * Resolved by alias rather than through `ctx.auth()` so the login host does not require
+   * `AuthServiceAppend` on the context it is given — a plugin can adopt a token on any context that
+   * carries the auth service, including one it did not build.
+   *
+   * Going through `AuthService.update` matters: it stores the record, decodes the envelope and sets
+   * both `auth` and `token` in one place. Writing those three by hand — which is what the popup and
+   * the MUI relying party each used to do — leaves the same state on a good day and diverges the
+   * moment any of it changes.
+   */
+  adoptToken: (token: string) => Promise<void>
+  /**
+   * The one path this context's authentication is dropped, and the exact mirror of {@link adoptToken}.
+   *
+   * `undefined`, not `null`: `undefined` is the declared clearing value, and on the web the auth
+   * service reacts to it by navigating to the dispatcher. Everything that signs a user out goes
+   * through here — the hook, both browser plugins and the surrogate screen — so there is one place
+   * where "signed out" is defined rather than four that agree until one of them changes.
+   */
+  revokeToken: () => Promise<void>
+}

package/src/login/adopt.ts

@@ -1,19 +1,26 @@
 import type { AuthService } from '@owlmeans/auth-common'
+import { memoHelper } from '@owlmeans/context'
 import { DEFAULT_ALIAS as AUTH_ALIAS } from '../consts.js'
 import type { LoginContext } from './types.js'
+import type { LoginTokenHelper } from './adopt/types.js'
 
-/**
- * The one path an issued bearer token becomes this context's authentication.
- *
- * Resolved by alias rather than through `ctx.auth()` so the login host does not require
- * `AuthServiceAppend` on the context it is given — a plugin can adopt a token on any context that
- * carries the auth service, including one it did not build.
- *
- * Going through `AuthService.update` matters: it stores the record, decodes the envelope and sets
- * both `auth` and `token` in one place. Writing those three by hand — which is what the popup and
- * the MUI relying party each used to do — leaves the same state on a good day and diverges the
- * moment any of it changes.
- */
-export const adoptToken = async (ctx: LoginContext, token: string): Promise<void> => {
-  await ctx.service<AuthService>(AUTH_ALIAS).update(token)
+export const makeLoginTokenHelper = (ctx: LoginContext): LoginTokenHelper => {
+  const adoptToken = async (token: string): Promise<void> => {
+    await ctx.service<AuthService>(AUTH_ALIAS).update(token)
+  }
+
+  const revokeToken = async (): Promise<void> => {
+    await ctx.service<AuthService>(AUTH_ALIAS).update(undefined)
+  }
+
+  return { adoptToken, revokeToken }
 }
+
+/** The token helper of a context — one per context. */
+export const loginTokenOf = memoHelper.oncePer(makeLoginTokenHelper)
+
+/** @deprecated compat:factory-refactor — use `loginTokenOf(ctx).adoptToken(…)` */
+export const adoptToken = async (ctx: LoginContext, token: string): Promise<void> => loginTokenOf(ctx).adoptToken(token)
+
+/** @deprecated compat:factory-refactor — use `loginTokenOf(ctx).revokeToken()` */
+export const revokeToken = async (ctx: LoginContext): Promise<void> => loginTokenOf(ctx).revokeToken()

package/src/login/consts.local.ts

@@ -0,0 +1,34 @@
+import { LoginOutcome } from './consts.js'
+import type { CSSProperties } from 'react'
+
+/**
+ * The page the card sits in.
+ *
+ * It carries its own viewport height because this screen is rendered straight out of the
+ * dispatcher, into whatever the application happens to have around it — which is usually nothing
+ * with a height, so a percentage minimum would resolve to zero and leave the card at the top.
+ */
+export const page: CSSProperties = {
+  display: 'flex', alignItems: 'center', justifyContent: 'center',
+  minHeight: '100dvh', padding: '1rem',
+  fontFamily: 'system-ui, sans-serif', lineHeight: 1.5,
+}
+
+// Centred throughout, so the plain screen and the styled one read the same way.
+export const box: CSSProperties = {
+  width: '100%', maxWidth: '24rem', padding: '1.5rem', textAlign: 'center',
+}
+
+/** The same English fallback a document's `i18nKey` translates to when nothing else names it. */
+export const DEFAULT_LABEL: Record<string, string> = {
+  terms: 'Terms & Conditions',
+  privacy: 'Privacy Policy',
+  cookies: 'Cookie Policy',
+  billing: 'Billing Terms',
+  product: '{{product}} Product Terms',
+}
+
+/** Outcomes after which nobody was signed in, so a screen parked for the landing must not wait. */
+export const UNSIGNED_OUTCOMES: ReadonlySet<LoginOutcome> = new Set<LoginOutcome>([
+  LoginOutcome.Blocked, LoginOutcome.Failed, LoginOutcome.Gesture,
+])

package/src/login/consts.ts

@@ -5,20 +5,120 @@ export const LOGIN_SERVICE = DEFAULT_ALIAS
 /** Priority of a plugin that makes no claim about the environment. */
 export const DEFAULT_LOGIN_PRIORITY = 0
 
+/** Order given to a method that declares none. */
+export const DEFAULT_METHOD_ORDER = 100
+
 /**
- * Name given to the surrogate login window, and the marker it records about itself.
+ * Name given to the surrogate login window, the marker it records about itself, and the values the
+ * two documents exchange.
  *
- * These values are a wire protocol between two documents that may be running different builds —
- * an opener holding an older bundle and a surrogate freshly loaded, or the reverse. They are
- * therefore fixed, and must never be "tidied" to match a newer vocabulary.
+ * These are a wire protocol between two documents that may be running different builds — an opener
+ * holding an older bundle and a surrogate freshly loaded, or the reverse. They are therefore fixed,
+ * and must never be "tidied" to match a newer vocabulary. That applies to the query names and the
+ * message types added later just as much as to the original three.
  */
 export const LOGIN_SURROGATE_NAME = 'owlmeans-oidc-login'
 
 export const LOGIN_TOKEN_MESSAGE = 'owlmeans:oidc:popup-token'
 
+export const LOGIN_LOGOUT_MESSAGE = 'owlmeans:oidc:popup-logout'
+
 export const LOGIN_SURROGATE_MARKER = '_owlmeans-oidc-popup'
 
-export const LOGIN_SURROGATE_FEATURES = 'popup=yes,width=520,height=760'
+export const LOGIN_SURROGATE_WIDTH = 520
+
+export const LOGIN_SURROGATE_HEIGHT = 760
+
+/**
+ * @deprecated Never centered the window — it carried no `left`/`top`, so the surrogate always
+ * opened wherever the browser's own default popup placement put it. Superseded by
+ * `@owlmeans/web-client`'s `centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT)`,
+ * computed fresh per call since centering depends on where the browser window currently sits.
+ * Kept, unchanged, for the same reason as the rest of this block: an already-generated app may
+ * carry a copy of code that still imports it.
+ */
+export const LOGIN_SURROGATE_FEATURES =
+  `popup=yes,width=${LOGIN_SURROGATE_WIDTH},height=${LOGIN_SURROGATE_HEIGHT}`
 
 /** How often a surrogate window is checked for having been closed by the user. */
 export const LOGIN_WATCH_INTERVAL = 500
+
+/** Carries WHY the surrogate window was opened across the window boundary. */
+export const LOGIN_INTENT_QUERY = 'intent'
+
+/**
+ * Carries the address the surrogate should run, so the flow parameters the opener's URL held are
+ * forwarded rather than discarded.
+ */
+export const LOGIN_NEXT_QUERY = 'next'
+
+/**
+ * Carries the method the user already chose, one window up.
+ *
+ * A surrogate acting on it is not an auto-redirect in the "never choose for the user" sense: the
+ * choice was made, by a person, in the document that opened this one.
+ */
+export const LOGIN_METHOD_QUERY = 'method'
+
+/** Where a browser records that it agreed to one exact set of legal documents. */
+export const LOGIN_TERMS_STORAGE = '_owlmeans-login-terms'
+
+/**
+ * Bound on a single step's `pending` check, or a landing hook's `landed` call.
+ *
+ * A step/hook that hangs must never HANG sign-in itself — both `continueLogin` and
+ * `landAfterLogin` treat a timeout exactly like a rejection, resolving within this budget either
+ * way. What that resolves TO is fail-open ("not pending") for an ordinary step, and fail-closed
+ * ("pending") for one that declared itself `required` — see `continueLogin`'s `onBroken`.
+ */
+export const LOGIN_STEP_TIMEOUT = 5_000
+
+/** Where a browser records the last token a landing hook has already run for. */
+export const LOGIN_LANDED_STORAGE = '_owlmeans-login-landed'
+
+/** What a dispatcher does once `login().resume(...)` has answered. */
+export enum ResumeAction {
+  /** The plugin took it over — the browser is leaving, or the window is closing. */
+  Stop = 'stop',
+  /** Render the outcome to the user; there is nothing further to do automatically. */
+  Render = 'render',
+  /** Ordinary tab: keep the session and carry on to the application. */
+  Navigate = 'navigate',
+}
+
+/** 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',
+}
+
+/**
+ * How long a sign-in aimed at a screen (`LoginRequest.target`) keeps that screen parked: long
+ * enough for a sign-in with an emailed code, short enough that a tab abandoned mid-way never lands
+ * a later, unrelated sign-in on it.
+ */
+export const LOGIN_TARGET_TTL = 30 * 60 * 1000

package/src/login/credit/types.ts

@@ -0,0 +1,6 @@
+export interface ResolvedCredit {
+  /** Whether "Powered by OwlMeans" is rendered. */
+  poweredBy: boolean
+  /** The product and organization line, already composed. Null when there is nothing to say. */
+  line: string | null
+}

package/src/login/credit.ts

@@ -0,0 +1,69 @@
+import type { BrandSettings, LoginCreditConfig } from '@owlmeans/config'
+import type { ResolvedCredit } from './credit/types.js'
+
+/**
+ * The years one notice covers.
+ *
+ * A range only while the first year is genuinely in the past — an app configured with the current
+ * year, or with a year a skewed clock puts in the future, still gets a well-formed notice rather
+ * than `© 2026–2026` or a range that runs backwards.
+ */
+const years = (since: number | undefined, now: number): string =>
+  since != null && since > 0 && since < now ? `${since}–${now}` : `${now}`
+
+/**
+ * A configured value that was actually SET.
+ *
+ * Empty is how a build-time default spells "unset", and this config is filled from environment
+ * variables a platform delivers — `BRANDING_ORGANIZATION: meta.brandingOrganization ?? ''` is the
+ * shape of every one of them. `??` does not fall through an empty string, so an undelivered
+ * organization used to win the fallback chain and compose a line ending in a bare dash.
+ */
+const set = (value?: string | null): string | null =>
+  value != null && value.trim() !== '' ? value : null
+
+/**
+ * What the bottom of the sign-in screen says.
+ *
+ * It is a copyright notice, so it is composed as one: `© <year> <holder>`. That is the whole
+ * reason `copyright` defaults to on — the name on its own reads as a caption, and an application
+ * that means to assert a copyright would have had to write the mark and the year into a literal
+ * `line` to get one.
+ *
+ * The organization falls back to its slug because an organization record carries no readable name
+ * — so "no name" is the ordinary case, not an error, and a screen that rendered an empty line for
+ * it would be worse than one that renders the slug.
+ *
+ * `line` replaces everything when an app supplies it: a product with its own legal wording should
+ * not have to defeat a composition rule to use it.
+ */
+export const resolveCredit = (
+  cfg?: LoginCreditConfig, brand?: BrandSettings, service?: string
+): ResolvedCredit => {
+  const poweredBy = cfg?.poweredBy ?? true
+  const literal = set(cfg?.line)
+  if (literal != null) {
+    return { poweredBy, line: literal }
+  }
+
+  const product = set(cfg?.product) ?? set(brand?.name) ?? set(service)
+  const organization = set(cfg?.organization) ?? set(brand?.organization)
+    ?? set(cfg?.entity) ?? set(brand?.entity)
+
+  // Whoever the notice names. A product with no organization behind it holds its own copyright,
+  // which is why this falls through to the product rather than dropping the notice.
+  const holder = set(cfg?.holder) ?? organization ?? product
+  const wording = typeof cfg?.copyright === 'string' ? set(cfg.copyright) : null
+  const notice = cfg?.copyright === false || holder == null
+    ? organization
+    : wording ?? `© ${years(cfg?.since, new Date().getFullYear())} ${holder}`
+
+  // The product is named beside the notice only when it is not already the thing being claimed —
+  // "OwlMeans — © 2026 OwlMeans" says the name twice and neither time usefully.
+  return {
+    poweredBy,
+    line: product != null && notice != null && product !== holder
+      ? `${product} — ${notice}`
+      : notice ?? product,
+  }
+}

package/src/login/env/types.ts

@@ -0,0 +1,35 @@
+import type { LoginEnv } from '../types.js'
+
+/** What this browsing context is for a sign-in: framed, the surrogate window, opened by another. */
+export interface LoginEnvHelper {
+  /**
+   * Whether this document is embedded in a frame.
+   *
+   * Reading `window.top` across origins throws, and that throw is itself the answer: a `top` that
+   * differs and a `top` that cannot be reached both mean "framed".
+   */
+  isEmbedded: () => boolean
+  /**
+   * Record that this window is the surrogate login window, while that is still knowable.
+   *
+   * Must run on the surrogate's **first** load, before the flow navigates to the provider:
+   * `window.name` is the only evidence at that point, and browsers clear it as soon as a top-level
+   * context goes cross-origin — so by the time the provider redirects back, the name is gone and
+   * this window would look like an ordinary tab.
+   *
+   * Idempotent, and a no-op in every window that is not the surrogate.
+   */
+  markSurrogate: () => void
+  /** Whether this document is the surrogate login window. */
+  isSurrogate: () => boolean
+  /** Forget the surrogate marker — called once its token has been handed back. */
+  clearSurrogate: () => void
+  /**
+   * Default login environment.
+   *
+   * The single source of environment truth for cascade selection — a plugin's `match` reads this
+   * and never probes `window` itself, so a non-DOM host can drive the same plugins by supplying its
+   * own descriptor.
+   */
+  defaultLoginEnv: () => LoginEnv
+}