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

package/src/login/service.ts

@@ -1,10 +1,19 @@
-import { createLazyService } from '@owlmeans/context'
-import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { DEFAULT_ALIAS } from './consts.js'
-import { defaultLoginEnv } from './env.js'
-import { adoptToken } from './adopt.js'
-import { LoginOutcome } from './types.js'
-import type { LoginContext, LoginPlugin, LoginService, LoginServiceAppend } from './types.js'
+import { createLazyService, type BasicConfig, type BasicContext } from '@owlmeans/context'
+import type { CommonConfig } from '@owlmeans/config'
+import type { ClientContext } from '@owlmeans/client'
+import { flowLandingOf } from '@owlmeans/client-flow'
+import { logger } from '@owlmeans/log'
+import { DEFAULT_ALIAS, LOGIN_TARGET_TTL, LoginOutcome } from './consts.js'
+import { UNSIGNED_OUTCOMES } from './consts.local.js'
+import { loginEnvHelper } from './env.js'
+import { loginTokenOf } from './adopt.js'
+import { loginMethodsHelper } from './methods.js'
+import type {
+  LoginContext, LoginLandingHook, LoginMethodSource, LoginNotifier, LoginPlugin, LoginPrecondition,
+  LoginRequest, LoginScreenComponent, LoginService, LoginServiceAppend, LoginStep
+} from './types.js'
+
+const log = logger('client-auth:login')
 
 /**
  * Login service = plugin host. It holds a registry of login plugins and, on every facade call,
@@ -19,15 +28,61 @@ import type { LoginContext, LoginPlugin, LoginService, LoginServiceAppend } from
  * stage. `context.service()` throws for an uninitialized non-lazy service, which would make
  * `ensureLoginService` fail exactly where apps are told to call it.
  *
- * `begin` is deliberately NOT `async`. An async facade method defers the plugin's body past a
- * microtask boundary, and a `window.open` that lands after the user gesture has finished being
- * handled is eaten by the popup blocker. The same rule binds every plugin's own `begin`.
+ * `begin` and `logout` are deliberately NOT `async`. An async facade method defers the plugin's
+ * body past a microtask boundary, and a `window.open` that lands after the user gesture has
+ * finished being handled is eaten by the popup blocker. The same rule binds every plugin's own
+ * `begin` and `logout`, and it is why a precondition must be synchronous too.
  */
 export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService => {
   const plugins: LoginPlugin[] = []
+  const preconditions: LoginPrecondition[] = []
+  const methodSources: LoginMethodSource[] = []
+  const steps: LoginStep[] = []
+  const hooks: LoginLandingHook[] = []
+  let screen: LoginScreenComponent | null = null
+  let notifier: LoginNotifier | null = null
 
   const ctx = (): LoginContext => service.ctx as LoginContext
 
+  /**
+   * Park `request.target` for the post-sign-in landing, and hand back the request whose continuation
+   * waits for that write.
+   *
+   * The write is STARTED here and never awaited on the way in: `begin` must reach the plugin's
+   * `window.open` inside the gesture. Only the continuation waits — the redirect plugin's in-app hop
+   * to the dispatcher and the surrogate's hop after the popup has handed its token back — so the
+   * dispatcher that resumes the landing always finds the record, whatever the storage behind it.
+   * A write that fails costs the landing, never the sign-in.
+   */
+  const parkTarget = (
+    ctx: LoginContext, request: LoginRequest
+  ): [LoginRequest, Promise<boolean> | null] => {
+    if (request.target == null || request.target === '') {
+      return [request, null]
+    }
+    const parked = flowLandingOf(ctx as unknown as ClientContext).suspendLanding(
+      { entrypoint: request.target, query: {} },
+      { expiresAt: Date.now() + LOGIN_TARGET_TTL }
+    ).catch((error: unknown) => {
+      log.warn('Could not park the sign-in target; the landing falls back', {
+        target: request.target, error,
+      })
+
+      return false
+    })
+    const navigate = request.navigate
+
+    return [
+      navigate == null ? request : {
+        ...request, navigate: async () => {
+          await parked
+          await navigate()
+        },
+      },
+      parked,
+    ]
+  }
+
   const service: LoginService = createLazyService<LoginService>(alias, {
     registerPlugin: (plugin: LoginPlugin) => {
       const existing = plugins.findIndex(candidate => candidate.alias === plugin.alias)
@@ -38,8 +93,59 @@ export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService =>
       plugins.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
     },
 
+    registerPrecondition: (precondition: LoginPrecondition) => {
+      const existing = preconditions.findIndex(candidate => candidate.alias === precondition.alias)
+      if (existing >= 0) {
+        preconditions.splice(existing, 1)
+      }
+      preconditions.push(precondition)
+      preconditions.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+    },
+
+    registerMethodSource: (source: LoginMethodSource) => {
+      const existing = methodSources.findIndex(candidate => candidate.alias === source.alias)
+      if (existing >= 0) {
+        methodSources.splice(existing, 1)
+      }
+      methodSources.push(source)
+    },
+
+    methods: methodCtx => loginMethodsHelper.resolveLoginMethods(
+      methodCtx,
+      (methodCtx.context.cfg as CommonConfig).security?.auth?.login,
+      methodSources
+    ),
+
+    registerScreen: value => { screen = value },
+
+    screen: () => screen,
+
+    registerNotifier: value => { notifier = value },
+
+    registerStep: (step: LoginStep) => {
+      const existing = steps.findIndex(candidate => candidate.alias === step.alias)
+      if (existing >= 0) {
+        steps.splice(existing, 1)
+      }
+      steps.push(step)
+      steps.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+    },
+
+    steps: () => [...steps],
+
+    onLanded: (hook: LoginLandingHook) => {
+      const existing = hooks.findIndex(candidate => candidate.alias === hook.alias)
+      if (existing >= 0) {
+        hooks.splice(existing, 1)
+      }
+      hooks.push(hook)
+      hooks.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+    },
+
+    landingHooks: () => [...hooks],
+
     plugin: env => {
-      const environment = env ?? defaultLoginEnv()
+      const environment = env ?? loginEnvHelper.defaultLoginEnv()
       const plugin = plugins.find(
         candidate => candidate.match?.(environment, service.ctx as LoginContext | undefined) ?? true
       )
@@ -49,32 +155,89 @@ export const makeLoginService = (alias: string = DEFAULT_ALIAS): LoginService =>
       return plugin
     },
 
-    env: () => defaultLoginEnv(),
+    env: () => loginEnvHelper.defaultLoginEnv(),
 
     enter: () => {
-      const env = defaultLoginEnv()
+      const env = loginEnvHelper.defaultLoginEnv()
       service.plugin(env).enter?.(ctx(), env)
     },
 
     begin: request => {
-      const env = defaultLoginEnv()
+      const env = loginEnvHelper.defaultLoginEnv()
+      // Synchronously, before anything can open a window: a precondition that refuses leaves the
+      // user exactly where `Gesture` describes — unable to proceed until they act again.
+      for (const precondition of preconditions) {
+        if (!precondition.check(ctx(), request, env)) {
+          return Promise.resolve(LoginOutcome.Gesture)
+        }
+      }
+
+      // Parked only past the preconditions: a refused attempt leaves no landing behind for the
+      // next, unrelated sign-in to resume.
+      const [parkedRequest, parked] = parkTarget(ctx(), request)
+
+      // Notified here, in the facade, rather than by each caller: `useLogin` fires the flow and
+      // forgets the result, and this is the one place every caller — the header hook and the
+      // sign-in screen's method buttons alike — passes through on the way to a settled outcome.
+      return service.plugin(env).begin(ctx(), parkedRequest, env).then(outcome => {
+        if (parked != null && UNSIGNED_OUTCOMES.has(outcome)) {
+          void parked.then(async () => {
+            await flowLandingOf(ctx() as unknown as ClientContext).discardSuspendedLanding()
+          })
+        }
+        notifier?.(outcome, env)
 
-      return service.plugin(env).begin(ctx(), request, env)
+        return outcome
+      })
     },
 
     authorize: async url => {
-      const env = defaultLoginEnv()
+      const env = loginEnvHelper.defaultLoginEnv()
 
       return await service.plugin(env).authorize(ctx(), url, env)
     },
 
     complete: async token => {
-      const env = defaultLoginEnv()
+      const env = loginEnvHelper.defaultLoginEnv()
 
       return await service.plugin(env).complete(ctx(), token, env)
     },
 
-    adopt: async token => { await adoptToken(ctx(), token) },
+    resume: async token => {
+      const env = loginEnvHelper.defaultLoginEnv()
+      // Absent means "keep it and carry on" — which is what an ordinary tab has always done, and
+      // is why the redirect plugin implements nothing here.
+      return await service.plugin(env).resume?.(ctx(), token, env) ?? LoginOutcome.Passed
+    },
+
+    logout: request => {
+      const env = loginEnvHelper.defaultLoginEnv()
+      const plugin = service.plugin(env)
+      if (plugin.logout == null) {
+        // A plugin with no logout mechanic still has to end the session it started.
+        return loginTokenOf(ctx()).revokeToken().then(async () => {
+          await request.navigate?.()
+
+          return LoginOutcome.Passed
+        })
+      }
+
+      return plugin.logout(ctx(), request, env).then(outcome => {
+        notifier?.(outcome, env)
+
+        return outcome
+      })
+    },
+
+    logoutComplete: async () => {
+      const env = loginEnvHelper.defaultLoginEnv()
+
+      return await service.plugin(env).logoutComplete?.(ctx(), env) ?? LoginOutcome.Passed
+    },
+
+    adopt: async token => { await loginTokenOf(ctx()).adoptToken(token) },
+
+    revoke: async () => { await loginTokenOf(ctx()).revokeToken() },
   })
 
   return service

package/src/login/start/types.ts

@@ -0,0 +1,30 @@
+import type { LoginOutcome } from '../consts.js'
+
+/** What a "Log in" control hands `startLogin`: where the flow starts, where it lands, how to move. */
+export interface LoginStart {
+  /** The resolved dispatcher path — where the login flow starts. */
+  url: string
+  /** Entrypoint alias to land on once signed in; absent means the ordinary landing. */
+  target?: string
+  /** The in-app navigation, supplied by a component because only a component may hold one. */
+  go: (alias: string) => void | Promise<void>
+}
+
+/** The decision behind a "Log in" control, bound to the application context. */
+export interface LoginStartHelper {
+  /**
+   * What a "Log in" control does when clicked — the decision behind `useLogin`, kept free of React so
+   * it is the same rule wherever a control is rendered.
+   *
+   * - A target and a session already here: go straight to the target — there is nobody to sign in.
+   * - Otherwise: begin a sign-in whose continuation is ALWAYS the dispatcher, never the target. A
+   *   target travels as `LoginRequest.target`, which the facade parks for the landing; the
+   *   dispatcher's own post-sign-in landing (`landAfterLogin` — landing hooks, pending steps such as a
+   *   consent screen, then the parked target) brings the person there signed in. Navigating to a
+   *   guarded target instead is what used to land a person on it signed out.
+   *
+   * NOT async, and nothing is awaited before `begin`: the surrogate plugin opens its window inside
+   * this call, and a window opened after the gesture has been handled is eaten by the popup blocker.
+   */
+  startLogin: (start: LoginStart) => Promise<LoginOutcome>
+}

package/src/login/start.ts

@@ -0,0 +1,44 @@
+import { DISPATCHER } from '@owlmeans/auth'
+import type { AuthService } from '@owlmeans/auth-common'
+import { DEFAULT_ALIAS as AUTH_ALIAS } from '../consts.js'
+import { LOGIN_SERVICE, LoginOutcome } from './consts.js'
+import type { LoginContext, LoginService } from './types.js'
+import { memoHelper } from '@owlmeans/context'
+import type { LoginStartHelper } from './start/types.js'
+
+export const makeLoginStartHelper = (ctx: LoginContext): LoginStartHelper => {
+  /**
+   * Whether this document already holds a session, answered WITHOUT awaiting anything.
+   *
+   * Read off the auth service's in-memory token, which every guard and `authenticated()` call fills.
+   * A session not yet read from storage answers `false` and costs nothing: the sign-in it starts finds
+   * the session at the dispatcher, which lands on the parked target all the same.
+   */
+  const holdsSession = (): boolean => {
+    if (!ctx.hasService(AUTH_ALIAS)) {
+      return false
+    }
+    const token = ctx.service<AuthService>(AUTH_ALIAS).token
+
+    return token != null && token !== ''
+  }
+
+  const startLogin: LoginStartHelper['startLogin'] = start => {
+    const { url, target, go } = start
+    if (target != null && target !== '' && holdsSession()) {
+      return Promise.resolve(go(target)).then(() => LoginOutcome.Handled)
+    }
+
+    return ctx.service<LoginService>(LOGIN_SERVICE).begin({
+      url,
+      target,
+      // Only a component may call `useNavigate`, so the in-app continuation is handed to the
+      // plugin rather than reinvented by it.
+      navigate: () => { void go(DISPATCHER) },
+    })
+  }
+
+  return { startLogin }
+}
+
+export const loginStartOf = memoHelper.oncePer(makeLoginStartHelper)

package/src/login/surrogate/types.ts

@@ -0,0 +1,9 @@
+import type { LoginIntent } from '../consts.js'
+
+export interface SurrogateTarget {
+  intent: LoginIntent
+  /** The address the surrogate should actually run, once it is one window up. */
+  next?: string
+  /** The method the user already chose in the opener. */
+  method?: string
+}

package/src/login/surrogate.ts

@@ -0,0 +1,37 @@
+import { DISPATCHER_SURROGATE } from '@owlmeans/auth'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { LOGIN_INTENT_QUERY, LOGIN_METHOD_QUERY, LOGIN_NEXT_QUERY } from './consts.js'
+import type { LoginContext } from './types.js'
+import type { SurrogateTarget } from './surrogate/types.js'
+
+/**
+ * Where a surrogate window opens.
+ *
+ * Returns `null` when the application's entrypoint list predates the surrogate route — an app
+ * built against an older `@owlmeans/auth-common` has no such entrypoint, and the caller then falls
+ * back to opening the dispatcher directly, which is exactly what it used to do. That fallback is
+ * the whole compatibility story for already-deployed applications, so it must never be removed in
+ * favour of throwing.
+ */
+export const surrogatePath = (ctx: LoginContext, target: SurrogateTarget): string | null => {
+  if (!ctx.hasEntrypoint(DISPATCHER_SURROGATE)) {
+    return null
+  }
+  let path: string
+  try {
+    path = ctx.entrypoint<ClientEntrypoint>(DISPATCHER_SURROGATE).path()
+  } catch {
+    return null
+  }
+
+  const query = new URLSearchParams()
+  query.set(LOGIN_INTENT_QUERY, target.intent)
+  if (target.next != null && target.next !== '') {
+    query.set(LOGIN_NEXT_QUERY, target.next)
+  }
+  if (target.method != null && target.method !== '') {
+    query.set(LOGIN_METHOD_QUERY, target.method)
+  }
+
+  return `${path}?${query.toString()}`
+}

package/src/login/terms/types.ts

@@ -0,0 +1,126 @@
+import type { LoginTermsConfig } from '@owlmeans/config'
+import type { LoginContext } from '../types.js'
+
+/** One document (or notice) a sign-in screen links to. */
+export interface ResolvedTermsDocument {
+  key: string
+  href: string
+  /** Published translations, selected at render/record time; `href` remains canonical. */
+  hrefMap?: Record<string, string>
+  /** A caller's own label, already resolved to one string — only ever set for a custom document. */
+  label?: string
+  /** A locale map for the label, when the config supplied one — resolved by the renderer, not here. */
+  labelMap?: Record<string, string>
+  /** Translation key under `login.terms.*`, when this document has one. */
+  i18nKey?: string
+  revisedAt?: string
+  /** Extra interpolation values for `i18nKey`'s translation (e.g. `{ product: 'Acme' }`). */
+  params?: Record<string, string>
+}
+
+export interface ResolvedTerms {
+  required: boolean
+  terms: string
+  privacy: string
+  cookies?: string
+  version: string
+  /** What the checkbox agrees to — terms, then billing/product when configured, then custom. */
+  documents: ResolvedTermsDocument[]
+  /** What is merely DISCLOSED, never consented to — privacy, plus cookies per the rule below. */
+  notices: ResolvedTermsDocument[]
+  /** The latest `revisedAt` among {@link documents}. Only set when `showRevision` is true. */
+  revisedAt?: string
+  showRevision: boolean
+}
+
+/** One document as `@owlmeans/marketing-consent`'s `TermsDocumentRef` shape — structurally, with
+ * no dependency on that package (client-auth is a layer below it). */
+export interface TermsAcceptanceRef {
+  key: string
+  href: string
+  revisedAt?: string
+}
+
+/** One fragment of an interpolated terms sentence — plain text, or a link to a document. */
+export interface TermsSentencePart {
+  text: string
+  href?: string
+  documentKey?: string
+}
+
+/** What a sign-in-time terms acceptance sends the server. */
+export interface LoginTermsAcceptance {
+  documents: TermsAcceptanceRef[]
+  notices: TermsAcceptanceRef[]
+  version: string
+  locale?: string
+}
+
+/** The documents a sign-in agrees to: their resolution, the local acceptance record and the sentence. */
+export interface LoginTermsHelper {
+  /** The configured documents and notices, with the version acceptance is recorded against; null when terms are off. */
+  resolveTerms: (cfg?: LoginTermsConfig | false) => ResolvedTerms | null
+  /**
+   * Whether this browser has already agreed to exactly these documents.
+   *
+   * `localStorage` and not a cookie: the record is a UI convenience, it never travels to a server,
+   * and it must be readable by the surrogate login window — which is same-origin, so it sees the
+   * opener's acceptance and does not ask twice. A preview iframe on a different origin gets its own
+   * partition and therefore its own acceptance, which is correct rather than unfortunate.
+   */
+  termsAccepted: (resolved: ResolvedTerms | null) => boolean
+  /** Record (or, with `accepted: false`, forget) this browser's agreement to these documents. */
+  acceptTerms: (resolved: ResolvedTerms | null, accepted: boolean) => void
+  /**
+   * A document's own label: a caller's literal `label`, else its `labelMap` for the current locale,
+   * else its `i18nKey` translated — each with `params` (e.g. `{ product: 'Acme' }`) interpolated
+   * afterwards, since the `translate` contract every renderer shares is a plain
+   * `(key, defaultValue) => string` with no interpolation option of its own.
+   *
+   * The one label resolver every renderer of a terms sentence uses — `FallbackLoginScreen` here, and
+   * `@owlmeans/web-panel`'s `LoginTerms` — so the English fallbacks and the resolution order live in
+   * exactly one place instead of two hand-kept copies.
+   */
+  termsLabelResolver: (
+    translate: (key: string, defaultValue: string) => string, locale: string | undefined
+  ) => (doc: ResolvedTermsDocument) => string
+  /** Explicit locale destination, then base language, then canonical href; never rewrites paths. */
+  termsHrefOf: (doc: ResolvedTermsDocument, locale?: string) => string
+  /**
+   * What a sign-in-time terms acceptance sends the server — structurally
+   * `@owlmeans/marketing-consent`'s `TermsAcceptance`, so `client.recordTerms(termsAcceptanceOf(...))`
+   * type-checks with no dependency in this direction. Shared by `termsRecorder` (the sign-in screen's
+   * own local acceptance, copied at landing) and a Terms-mode consent screen recording the box it
+   * just showed.
+   */
+  termsAcceptanceOf: (
+    resolved: Pick<ResolvedTerms, 'documents' | 'notices' | 'version'>, locale?: string
+  ) => LoginTermsAcceptance
+  /**
+   * Whether the Terms confirmation has been moved off the sign-in screen onto a registered step.
+   *
+   * True only when a step both DECLARES `confirmsTerms` and is BOUND (`ctx.hasEntrypoint`) — an app
+   * that registers the step (e.g. `appendMarketingConsent({ terms: 'step' })`) but never binds its
+   * screen (an older target, a partial import) keeps the sign-in checkbox, fail-closed: a person must
+   * never find the confirmation missing from both places at once.
+   *
+   * Reads the service directly (`ctx.hasService`), never `ensureLoginService` — that registers an
+   * empty host as a side effect, which a render-time check must not do.
+   */
+  termsDeferred: (ctx: LoginContext) => boolean
+  /**
+   * Interpolate a translated sentence template around its document list(s).
+   *
+   * Supports `{{documents}}` (→ `resolved.documents`) and `{{notices}}` (→ `resolved.notices`), and
+   * — for backward compatibility with an older template string — the legacy `{{terms}}`, `{{privacy}}`
+   * and `{{cookies}}` placeholders, each resolved to its one matching document. Framework-agnostic on
+   * purpose: it returns plain data, never JSX, so both `@owlmeans/web-panel` and the plain fallback
+   * screen can turn the parts into their own markup.
+   */
+  termsSentence: (
+    template: string,
+    resolved: Pick<ResolvedTerms, 'documents' | 'notices'>,
+    locale: string | undefined,
+    resolveLabel: (doc: ResolvedTermsDocument) => string
+  ) => TermsSentencePart[]
+}

package/src/login/terms-config.ts

@@ -0,0 +1,55 @@
+/**
+ * Extra `LoginTermsConfig` fields, added by TypeScript module augmentation rather than by editing
+ * `@owlmeans/config` itself.
+ *
+ * `@owlmeans/config` has roughly 85 dependents, and every one of them sits in the same release
+ * closure — a config bump ripples through every package that pins a range against it, whether or
+ * not it touches sign-in. The fields below are needed by exactly one consumer family (the sign-in
+ * screen and its terms confirmation, all downstream of `@owlmeans/client-auth`), so they are
+ * declared here instead, merged onto the base interface by TypeScript's own declaration merging.
+ *
+ * This file must be part of whatever a consumer's own compilation actually loads, or the merge
+ * never happens — an ambient augmentation applies only once the compiler has read the file that
+ * declares it. `@owlmeans/client-auth/login`'s barrel (`./index.ts`) re-exports this module for
+ * exactly that reason, so ANY import from `@owlmeans/client-auth/login` — which every application
+ * wiring sign-in already has — pulls this augmentation into that program. An app that constructs a
+ * `LoginTermsConfig` literal in a file that imports NOTHING from `@owlmeans/client-auth/login`
+ * still benefits as long as some other file in the same `tsc` program does; if none does (an
+ * isolated leaf package that only ever imports `@owlmeans/config`), add
+ * `import type {} from '@owlmeans/client-auth/login'` to the file building the literal — an
+ * import with an empty type list, kept only to pull this file into that program's graph.
+ *
+ * `export {}` below is required, not decorative: without at least one top-level import/export this
+ * file is a SCRIPT to TypeScript, not a MODULE, and `declare module '@owlmeans/config'` inside a
+ * script augments the global scope instead of merging onto the named module's exports.
+ */
+declare module '@owlmeans/config' {
+  interface LoginTermsConfig {
+    /** `documents[].key` (or a custom document's own key) → the ISO date it was last revised. */
+    revisions?: Record<string, string>
+    /**
+     * Document/notice key → locale → published href. Opt-in; omitted locales use the canonical
+     * href. Renderers and acceptance evidence resolve the same current locale, while these
+     * translated destinations leave the canonical agreement version and revisions unchanged.
+     */
+    localizedHrefs?: Record<string, Record<string, string>>
+    /** Off by default. A bare string is `{ href }`. */
+    billing?: string | { href: string, revisedAt?: string } | false
+    /** Off by default. `name` is interpolated into the `login.terms.product` translation. */
+    product?: { name: string, href: string, revisedAt?: string } | false
+    /**
+     * Custom documents beyond terms/billing/product, in the order they are agreed to.
+     *
+     * `label` may be a locale map (`{ en: '...', fr: '...' }`) — resolved at RENDER time, by
+     * whichever renderer has the current locale, never here: this file stays locale-free.
+     */
+    documents?: Array<{
+      key: string, href: string, label?: string | Record<string, string>, i18nKey?: string,
+      revisedAt?: string,
+    }>
+    /** Show the latest revision date beneath the confirmation. Default false. */
+    showRevision?: boolean
+  }
+}
+
+export { }