@woodsportal/hubspot-kit 1.0.41-dev.4 → 1.0.41-dev.6

package/templates/module-hybrid-cdn/src/components/layout/starter-nav.tsx

@@ -1,26 +1,23 @@
 import { Link } from '@tanstack/react-router'
 
-import { ROUTES } from '@/config/routes'
+import { starterNavItems } from '@/config/starter-nav'
 
 export function StarterNav() {
   return (
     <header className="border-b border-[#cbd6e2] bg-white/90 backdrop-blur">
       <div className="mx-auto flex max-w-4xl items-center justify-between gap-4 px-6 py-3 sm:px-10">
         <span className="text-sm font-semibold text-[#0091ae]">WoodsCLI starter</span>
-        <nav className="flex gap-4 text-sm font-medium">
-          <Link
-            to={ROUTES.home}
-            className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
-            activeOptions={{ exact: true }}
-          >
-            Home
-          </Link>
-          <Link
-            to={ROUTES.guide}
-            className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
-          >
-            Developer guide
-          </Link>
+        <nav className="flex flex-wrap gap-4 text-sm font-medium">
+          {starterNavItems.map((item) => (
+            <Link
+              key={item.to}
+              to={item.to}
+              className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
+              activeOptions={{ exact: item.to === '/' }}
+            >
+              {item.label}
+            </Link>
+          ))}
         </nav>
       </div>
     </header>

package/templates/module-hybrid-cdn/src/config/starter-nav.ts

@@ -0,0 +1,9 @@
+import { ROUTES } from '@/config/routes'
+
+/** No-auth module navigation — edit once; StarterNav reads this file. */
+export const starterNavItems = [
+  { to: ROUTES.home, label: 'Home' },
+  { to: ROUTES.guide, label: 'Developer guide' },
+] as const
+
+export type StarterNavItem = (typeof starterNavItems)[number]

package/templates/module-hybrid-cdn/src/features/starter/components/starter-home.tsx

@@ -2,35 +2,33 @@ import { useStarterPreview } from '../hooks/use-starter-preview'
 import { STARTER_FEATURES, WOODSCLI_ABOUT } from '../content/woodscli-guide-content'
 
 export function StarterHome() {
-  const { title, tagline, showFeatureCards, accentColor, heroStyle } = useStarterPreview()
+  const { title, tagline, showFeatureCards, heroStyle } = useStarterPreview()
 
   return (
     <>
-      <div style={{ ['--starter-accent' as string]: accentColor }}>
-        <section
-          className={
-            heroStyle === 'minimal'
-              ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
-              : heroStyle === 'bold'
-                ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[#1c1c1f] text-white'
-                : 'px-6 py-14 sm:px-10 sm:py-16 bg-gradient-to-br from-[var(--starter-accent,#0091ae)] to-[#ff7a59] text-white'
-          }
-        >
-          <div className="mx-auto max-w-4xl">
-            <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
-              {WOODSCLI_ABOUT.package} · local dev
-            </p>
-            <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
-            <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
-            <p className="mt-6 text-sm opacity-75">
-              Module config overlay:{' '}
-              <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
-              {' · '}
-              Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
-            </p>
-          </div>
-        </section>
-      </div>
+      <section
+        className={
+          heroStyle === 'minimal'
+            ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
+            : heroStyle === 'bold'
+              ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[#1c1c1f] text-white'
+              : 'px-6 py-14 sm:px-10 sm:py-16 bg-gradient-to-br from-[var(--primary-color,#FF7A59)] to-[var(--secondary-color,#2797AF)] text-white'
+        }
+      >
+        <div className="mx-auto max-w-4xl">
+          <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
+            {WOODSCLI_ABOUT.package} · local dev
+          </p>
+          <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
+          <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
+          <p className="mt-6 text-sm opacity-75">
+            Module config overlay:{' '}
+            <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
+            {' · '}
+            Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
+          </p>
+        </div>
+      </section>
 
       {showFeatureCards ? (
         <div className="mx-auto grid max-w-4xl gap-4 px-6 py-10 sm:grid-cols-3 sm:px-10">
@@ -39,7 +37,7 @@ export function StarterHome() {
               key={feature.title}
               className="rounded-lg border border-[#cbd6e2] bg-white p-5 shadow-sm"
             >
-              <h2 className="text-sm font-semibold text-[#0091ae]">{feature.title}</h2>
+              <h2 className="text-sm font-semibold text-[var(--primary-color,#FF7A59)]">{feature.title}</h2>
               <p className="mt-2 text-sm leading-relaxed text-[#516f90]">{feature.body}</p>
             </article>
           ))}

package/templates/module-hybrid-cdn/src/features/starter/hooks/starter-preview-values.ts

@@ -2,7 +2,6 @@ export type StarterPreviewValues = {
   title: string
   tagline: string
   showFeatureCards: boolean
-  accentColor: string
   heroStyle: 'gradient' | 'minimal' | 'bold'
 }
 
@@ -21,8 +20,12 @@ function readContentField(module: Record<string, unknown>, key: string): unknown
   return module[key]
 }
 
-/** STYLE-tab fields may live under a `styles` group (fields.json) or flat legacy keys. */
+/** STYLE-tab fields may live under a `style` group (fields.json) or legacy `styles` / flat keys. */
 function readStyleField(module: Record<string, unknown>, key: string): unknown {
+  const style = module.style
+  if (style && typeof style === 'object' && key in (style as Record<string, unknown>)) {
+    return (style as Record<string, unknown>)[key]
+  }
   const styles = module.styles
   if (styles && typeof styles === 'object' && key in (styles as Record<string, unknown>)) {
     return (styles as Record<string, unknown>)[key]
@@ -31,8 +34,6 @@ function readStyleField(module: Record<string, unknown>, key: string): unknown {
 }
 
 export function mapStarterPreviewValues(module: Record<string, unknown>): StarterPreviewValues {
-  const accent = readStyleField(module, 'accent_color') as { color?: string } | undefined
-
   return {
     title: String(readContentField(module, 'title') ?? 'My HubSpot Portal'),
     tagline: String(
@@ -40,7 +41,6 @@ export function mapStarterPreviewValues(module: Record<string, unknown>): Starte
         'Customize this preview with Ctrl+Shift+Z, then replace this page with your portal app.',
     ),
     showFeatureCards: readContentField(module, 'show_feature_cards') !== false,
-    accentColor: accent?.color ?? '#0091ae',
     heroStyle: normalizeHeroStyle(readStyleField(module, 'hero_style')),
   }
 }

package/templates/module-monolith/public/fields.json

@@ -24,15 +24,58 @@
   },
   {
     "type": "group",
-    "name": "styles",
-    "label": "Styles",
+    "name": "style",
+    "label": "Style",
     "tab": "STYLE",
     "children": [
       {
-        "name": "accent_color",
-        "label": "Accent color",
-        "type": "color",
-        "default": { "color": "#0091ae", "opacity": 100 }
+        "type": "group",
+        "name": "module_global_colors",
+        "label": "Module Global Colors",
+        "tab": "STYLE",
+        "children": [
+          {
+            "name": "primary_color",
+            "label": "Primary Color",
+            "type": "color",
+            "default": {
+              "color": "#FF7A59",
+              "opacity": 100
+            }
+          },
+          {
+            "name": "secondary_color",
+            "label": "Secondary Color",
+            "type": "color",
+            "default": {
+              "color": "#2797AF",
+              "opacity": 100
+            }
+          },
+          {
+            "name": "button_text_color",
+            "label": "Button Text Color",
+            "type": "color",
+            "default": {
+              "color": "#FFFFFF",
+              "opacity": 100
+            }
+          }
+        ],
+        "default": {
+          "primary_color": {
+            "color": "#FF7A59",
+            "opacity": 100
+          },
+          "secondary_color": {
+            "color": "#2797AF",
+            "opacity": 100
+          },
+          "button_text_color": {
+            "color": "#FFFFFF",
+            "opacity": 100
+          }
+        }
       },
       {
         "name": "hero_style",

package/templates/module-monolith/src/assets/css/main.dev.css

@@ -1,5 +1,12 @@
 @import 'tailwindcss';
 
+/* WoodsPortal module global colors — defaults until HubSpot fields / module-config apply overrides */
+:root {
+  --primary-color: #ff7a59;
+  --secondary-color: #2797af;
+  --button-text-color: #ffffff;
+}
+
 /* Kit dev-module-config — paths relative to this file (src/assets/css/) */
 @source '../../../.wphs/.kit-module-config/**/*.{ts,tsx}';
 @source '../../../.wphs/.kit-bootstrap.tsx';

package/templates/module-monolith/src/components/layout/starter-nav.tsx

@@ -1,26 +1,23 @@
 import { Link } from '@tanstack/react-router'
 
-import { ROUTES } from '@/config/routes'
+import { starterNavItems } from '@/config/starter-nav'
 
 export function StarterNav() {
   return (
     <header className="border-b border-[#cbd6e2] bg-white/90 backdrop-blur">
       <div className="mx-auto flex max-w-4xl items-center justify-between gap-4 px-6 py-3 sm:px-10">
         <span className="text-sm font-semibold text-[#0091ae]">WoodsCLI starter</span>
-        <nav className="flex gap-4 text-sm font-medium">
-          <Link
-            to={ROUTES.home}
-            className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
-            activeOptions={{ exact: true }}
-          >
-            Home
-          </Link>
-          <Link
-            to={ROUTES.guide}
-            className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
-          >
-            Developer guide
-          </Link>
+        <nav className="flex flex-wrap gap-4 text-sm font-medium">
+          {starterNavItems.map((item) => (
+            <Link
+              key={item.to}
+              to={item.to}
+              className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
+              activeOptions={{ exact: item.to === '/' }}
+            >
+              {item.label}
+            </Link>
+          ))}
         </nav>
       </div>
     </header>

package/templates/module-monolith/src/config/starter-nav.ts

@@ -0,0 +1,9 @@
+import { ROUTES } from '@/config/routes'
+
+/** No-auth module navigation — edit once; StarterNav reads this file. */
+export const starterNavItems = [
+  { to: ROUTES.home, label: 'Home' },
+  { to: ROUTES.guide, label: 'Developer guide' },
+] as const
+
+export type StarterNavItem = (typeof starterNavItems)[number]

package/templates/module-monolith/src/features/starter/components/starter-home.tsx

@@ -2,35 +2,33 @@ import { useStarterPreview } from '../hooks/use-starter-preview'
 import { STARTER_FEATURES, WOODSCLI_ABOUT } from '../content/woodscli-guide-content'
 
 export function StarterHome() {
-  const { title, tagline, showFeatureCards, accentColor, heroStyle } = useStarterPreview()
+  const { title, tagline, showFeatureCards, heroStyle } = useStarterPreview()
 
   return (
     <>
-      <div style={{ ['--starter-accent' as string]: accentColor }}>
-        <section
-          className={
-            heroStyle === 'minimal'
-              ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
-              : heroStyle === 'bold'
-                ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[#1c1c1f] text-white'
-                : 'px-6 py-14 sm:px-10 sm:py-16 bg-gradient-to-br from-[var(--starter-accent,#0091ae)] to-[#ff7a59] text-white'
-          }
-        >
-          <div className="mx-auto max-w-4xl">
-            <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
-              {WOODSCLI_ABOUT.package} · local dev
-            </p>
-            <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
-            <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
-            <p className="mt-6 text-sm opacity-75">
-              Module config overlay:{' '}
-              <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
-              {' · '}
-              Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
-            </p>
-          </div>
-        </section>
-      </div>
+      <section
+        className={
+          heroStyle === 'minimal'
+            ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
+            : heroStyle === 'bold'
+              ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[#1c1c1f] text-white'
+              : 'px-6 py-14 sm:px-10 sm:py-16 bg-gradient-to-br from-[var(--primary-color,#FF7A59)] to-[var(--secondary-color,#2797AF)] text-white'
+        }
+      >
+        <div className="mx-auto max-w-4xl">
+          <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
+            {WOODSCLI_ABOUT.package} · local dev
+          </p>
+          <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
+          <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
+          <p className="mt-6 text-sm opacity-75">
+            Module config overlay:{' '}
+            <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
+            {' · '}
+            Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
+          </p>
+        </div>
+      </section>
 
       {showFeatureCards ? (
         <div className="mx-auto grid max-w-4xl gap-4 px-6 py-10 sm:grid-cols-3 sm:px-10">
@@ -39,7 +37,7 @@ export function StarterHome() {
               key={feature.title}
               className="rounded-lg border border-[#cbd6e2] bg-white p-5 shadow-sm"
             >
-              <h2 className="text-sm font-semibold text-[#0091ae]">{feature.title}</h2>
+              <h2 className="text-sm font-semibold text-[var(--primary-color,#FF7A59)]">{feature.title}</h2>
               <p className="mt-2 text-sm leading-relaxed text-[#516f90]">{feature.body}</p>
             </article>
           ))}

package/templates/module-monolith/src/features/starter/hooks/starter-preview-values.ts

@@ -2,7 +2,6 @@ export type StarterPreviewValues = {
   title: string
   tagline: string
   showFeatureCards: boolean
-  accentColor: string
   heroStyle: 'gradient' | 'minimal' | 'bold'
 }
 
@@ -21,8 +20,12 @@ function readContentField(module: Record<string, unknown>, key: string): unknown
   return module[key]
 }
 
-/** STYLE-tab fields may live under a `styles` group (fields.json) or flat legacy keys. */
+/** STYLE-tab fields may live under a `style` group (fields.json) or legacy `styles` / flat keys. */
 function readStyleField(module: Record<string, unknown>, key: string): unknown {
+  const style = module.style
+  if (style && typeof style === 'object' && key in (style as Record<string, unknown>)) {
+    return (style as Record<string, unknown>)[key]
+  }
   const styles = module.styles
   if (styles && typeof styles === 'object' && key in (styles as Record<string, unknown>)) {
     return (styles as Record<string, unknown>)[key]
@@ -31,8 +34,6 @@ function readStyleField(module: Record<string, unknown>, key: string): unknown {
 }
 
 export function mapStarterPreviewValues(module: Record<string, unknown>): StarterPreviewValues {
-  const accent = readStyleField(module, 'accent_color') as { color?: string } | undefined
-
   return {
     title: String(readContentField(module, 'title') ?? 'My HubSpot Portal'),
     tagline: String(
@@ -40,7 +41,6 @@ export function mapStarterPreviewValues(module: Record<string, unknown>): Starte
         'Customize this preview with Ctrl+Shift+Z, then replace this page with your portal app.',
     ),
     showFeatureCards: readContentField(module, 'show_feature_cards') !== false,
-    accentColor: accent?.color ?? '#0091ae',
     heroStyle: normalizeHeroStyle(readStyleField(module, 'hero_style')),
   }
 }

package/templates/scaffold/auth/_full/src/app.tsx

@@ -0,0 +1,172 @@
+import { useEffect, useRef, useState } from 'react'
+import { RouterProvider } from '@tanstack/react-router'
+import { installCrossTabSessionListener } from 'woodsportal-client-sdk'
+
+import { api } from '@/integrations/woodsportal-sdk'
+import * as TanStackQueryProvider from '@/integrations/tanstack-query/root-provider'
+import { env } from '@/env'
+import Loader from '@/components/ui/loader/loader'
+import { skipCurrentPublicPath } from '@/utils/ValidationSchema'
+import { isHubSpotCmsEditor } from '@/hubspot/is-cms-editor'
+import { navigateAfterFullAuth, navigateToLogin } from '@/features/auth/auth-navigation'
+import { isProtectedHashPath, readHashPathname, isPublicAuthRoute } from '@/features/auth/auth-route-paths'
+import { hardReplaceToHashPath } from '@/utils/safe-router-navigation'
+import {
+  isFullyAuthenticatedSession,
+  isMfaPendingSession,
+  recoverMfaGateOnBoot,
+} from '@/features/auth/auth-session'
+import { shouldBootstrapRefreshSession } from '@/features/auth/app-bootstrap-guards'
+import {
+  clearClientAuthSession,
+  registerClientSessionQueryClear,
+} from '@/features/auth/clear-client-auth-session'
+import { Routes } from '@/config/routes'
+import type { router } from '@/integrations/tanstack-router/router'
+
+const BOOTSTRAP_TIMEOUT_MS = 35_000
+
+type AppProps = {
+  router: typeof router
+}
+
+export function App({ router }: AppProps) {
+  const session = api.auth.session
+  const [isLoading, setIsLoading] = useState(true)
+  const inCmsEditor = isHubSpotCmsEditor()
+  const initialBootstrapDone = useRef(false)
+  const bootstrapStarted = useRef(false)
+
+  useEffect(() => {
+    const queryClient = TanStackQueryProvider.getContext().queryClient
+    registerClientSessionQueryClear(() => {
+      queryClient.cancelQueries()
+      queryClient.clear()
+    })
+    return installCrossTabSessionListener((kind) => {
+      if (kind === 'rev') {
+        clearClientAuthSession({ signalCrossTab: false })
+        queryClient.cancelQueries()
+        queryClient.clear()
+      }
+    })
+  }, [])
+
+  useEffect(() => {
+    if (bootstrapStarted.current) {
+      return
+    }
+    bootstrapStarted.current = true
+
+    if (!initialBootstrapDone.current) {
+      setIsLoading(true)
+    }
+
+    let mounted = true
+    const { logout } = api.auth.logout({})
+
+    const redirectProtectedPathToLogin = async (): Promise<void> => {
+      if (!skipCurrentPublicPath() || inCmsEditor) {
+        return
+      }
+      const hashPath = readHashPathname()
+      const routerPath = router?.state?.location?.pathname
+      const currentPath = routerPath && routerPath !== '/' ? routerPath : hashPath
+      const returnHref = router?.state?.location?.href ?? window.location.hash.replace(/^#/, '') ?? ''
+      const redirectPath =
+        currentPath !== Routes.login ? `?r=${encodeURIComponent(returnHref)}` : ''
+      const loginTarget = `${Routes.login}${redirectPath}`
+      await navigateToLogin(router, loginTarget)
+      if (isProtectedHashPath()) {
+        hardReplaceToHashPath(loginTarget)
+      }
+    }
+
+    const teardownAndRedirectToLogin = async (): Promise<void> => {
+      clearClientAuthSession()
+      try {
+        await logout()
+      } catch {
+        // stale session
+      }
+      await redirectProtectedPathToLogin()
+    }
+
+    const runBootstrap = async (): Promise<void> => {
+      await recoverMfaGateOnBoot()
+
+      const sessionRefreshExhausted = session.isSessionRefreshExhausted?.() ?? false
+      const refreshToken = session.getRefreshToken()
+      const hasRefresh =
+        !sessionRefreshExhausted &&
+        Boolean(refreshToken) &&
+        !session.isCookieExpired(env.VITE_REFRESH_TOKEN)
+
+      if (
+        !shouldBootstrapRefreshSession({
+          isMfaPendingSession: isMfaPendingSession(),
+          hasRefresh,
+          isPublicAuthRoute: isPublicAuthRoute(readHashPathname()),
+        })
+      ) {
+        if (!hasRefresh && skipCurrentPublicPath() && !inCmsEditor) {
+          await teardownAndRedirectToLogin()
+        }
+        return
+      }
+
+      try {
+        await session.refreshSession({ force: true })
+      } catch {
+        if (!inCmsEditor) {
+          await teardownAndRedirectToLogin()
+        }
+        return
+      }
+
+      if (isFullyAuthenticatedSession()) {
+        const hashPath = readHashPathname()
+        if (hashPath === Routes.twoFa || hashPath === Routes.login) {
+          navigateAfterFullAuth(router)
+        }
+      }
+    }
+
+    const bootstrap = async () => {
+      try {
+        await Promise.race([
+          runBootstrap(),
+          new Promise<never>((_, reject) => {
+            window.setTimeout(() => reject(new Error('bootstrap_timeout')), BOOTSTRAP_TIMEOUT_MS)
+          }),
+        ])
+      } catch (error) {
+        if (!inCmsEditor && skipCurrentPublicPath()) {
+          await teardownAndRedirectToLogin()
+        } else if (error instanceof Error && error.message !== 'bootstrap_timeout') {
+          throw error
+        }
+      } finally {
+        if (mounted) {
+          initialBootstrapDone.current = true
+          setIsLoading(false)
+        }
+      }
+    }
+
+    void bootstrap()
+    return () => {
+      mounted = false
+    }
+  }, [inCmsEditor, router])
+
+  if (isLoading) {
+    return <Loader showText={false} />
+  }
+
+  return (
+    <TanStackQueryProvider.Provider>
+      <RouterProvider router={router} />
+    </TanStackQueryProvider.Provider>
+  )
+}

package/templates/scaffold/auth/_full/src/config/auth-tier.ts

@@ -0,0 +1,4 @@
+/** Patched by `wp init-auth-scaffold` to `'starter' | 'sso' | 'full'`. */
+export const AUTH_SCAFFOLD_TIER = 'full' as const
+
+export type AuthScaffoldTier = typeof AUTH_SCAFFOLD_TIER

package/templates/scaffold/auth/_full/src/features/auth/auth-session.ts

@@ -0,0 +1,51 @@
+import {
+  api,
+  clearMfaPendingAccessToken,
+  hydrateMfaPendingAccessToken,
+  recoverMfaGateOnBoot as sdkRecoverMfaGateOnBoot,
+} from '@/integrations/woodsportal-sdk'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { clearMfaPendingState, getMfaPendingContext } from '@/features/auth/mfa-pending-storage'
+
+export function isMfaPendingSession(): boolean {
+  return getMfaPendingContext() != null && Boolean(api.auth.session.getAccessToken())
+}
+
+export function isFullyAuthenticatedSession(): boolean {
+  if (isMfaPendingSession()) {
+    return false
+  }
+  return api.auth.session.isFullyAuthenticated()
+}
+
+export function clearMfaPendingLoginSession(): void {
+  clearMfaPendingState()
+  clearMfaPendingAccessToken('c')
+  api.auth.session.clearAccessToken()
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent(AUTH_SESSION_CHANGED))
+  }
+}
+
+export type MfaBootRecoveryResult = 'pending' | 'orphan_cleared' | 'stale_token_cleared' | 'none'
+
+export async function recoverMfaGateOnBoot(): Promise<MfaBootRecoveryResult> {
+  return sdkRecoverMfaGateOnBoot({
+    hasMfaContext: () => getMfaPendingContext() != null,
+    hasAccessToken: () => Boolean(api.auth.session.getAccessToken()),
+    hasRefreshToken: () => Boolean(api.auth.session.getRefreshToken()),
+    clearMfaOrphan: () => clearMfaPendingLoginSession(),
+    clearStaleAccessToken: () => {
+      clearMfaPendingAccessToken('c')
+      api.auth.session.clearAccessToken()
+      if (typeof window !== 'undefined') {
+        window.dispatchEvent(new CustomEvent(AUTH_SESSION_CHANGED))
+      }
+    },
+    tryHydrateMfaAccessToken: () =>
+      hydrateMfaPendingAccessToken({
+        lane: 'c',
+        setAccessToken: (token, expiresIn) => api.auth.session.setAccessToken(token, expiresIn),
+      }),
+  })
+}