@vef-framework-react/starter 2.16.0 → 2.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. package/dist/cjs/components/index.cjs +1 -1
  2. package/dist/cjs/components/login/challenge-outlet.cjs +1 -0
  3. package/dist/cjs/components/login/index.cjs +1 -1
  4. package/dist/cjs/components/login/use-login-flow.cjs +1 -0
  5. package/dist/cjs/components/sso/index.cjs +1 -0
  6. package/dist/cjs/components/sso/styles.cjs +1 -0
  7. package/dist/cjs/components/sso/use-sso-login.cjs +1 -0
  8. package/dist/cjs/constants/index.cjs +1 -1
  9. package/dist/cjs/constants/router.cjs +1 -1
  10. package/dist/cjs/helpers/auth.cjs +1 -1
  11. package/dist/cjs/helpers/index.cjs +1 -1
  12. package/dist/cjs/index.cjs +1 -1
  13. package/dist/cjs/routes/index.cjs +1 -1
  14. package/dist/cjs/routes/login.cjs +1 -1
  15. package/dist/cjs/routes/sso.cjs +1 -0
  16. package/dist/es/components/access-denied/access-denied-icon.js +1 -1
  17. package/dist/es/components/access-denied/index.js +1 -1
  18. package/dist/es/components/app/index.js +1 -1
  19. package/dist/es/components/base-layout/index.js +1 -1
  20. package/dist/es/components/base-layout/styles.js +1 -1
  21. package/dist/es/components/base-layout/use-base-layout.js +1 -1
  22. package/dist/es/components/error/error-icon.js +1 -1
  23. package/dist/es/components/error/index.js +1 -1
  24. package/dist/es/components/index.js +9 -5
  25. package/dist/es/components/layout/components/contour-pattern.js +1 -1
  26. package/dist/es/components/layout/components/footer.js +1 -1
  27. package/dist/es/components/layout/components/header/app-switcher.js +1 -1
  28. package/dist/es/components/layout/components/header/boy-icon.js +1 -1
  29. package/dist/es/components/layout/components/header/color-scheme.js +1 -1
  30. package/dist/es/components/layout/components/header/fullscreen.js +1 -1
  31. package/dist/es/components/layout/components/header/girl-icon.js +1 -1
  32. package/dist/es/components/layout/components/header/header-pattern.js +1 -1
  33. package/dist/es/components/layout/components/header/index.js +1 -1
  34. package/dist/es/components/layout/components/header/menu-burger.js +1 -1
  35. package/dist/es/components/layout/components/header/menu-fold-left-icon.js +1 -1
  36. package/dist/es/components/layout/components/header/menu-unfold-left-icon.js +1 -1
  37. package/dist/es/components/layout/components/header/mixed-menu.js +1 -1
  38. package/dist/es/components/layout/components/header/search.js +1 -1
  39. package/dist/es/components/layout/components/header/theme-config.js +1 -1
  40. package/dist/es/components/layout/components/header/user-avatar.js +1 -1
  41. package/dist/es/components/layout/components/index.js +1 -1
  42. package/dist/es/components/layout/components/logo.js +1 -1
  43. package/dist/es/components/layout/components/menu.js +1 -1
  44. package/dist/es/components/layout/components/search/index.js +1 -1
  45. package/dist/es/components/layout/components/search/keyboard-arrow-down-icon.js +1 -1
  46. package/dist/es/components/layout/components/search/keyboard-arrow-up-icon.js +1 -1
  47. package/dist/es/components/layout/components/search/keyboard-control-icon.js +1 -1
  48. package/dist/es/components/layout/components/search/keyboard-esc-icon.js +1 -1
  49. package/dist/es/components/layout/components/search/keyboard-help.js +1 -1
  50. package/dist/es/components/layout/components/search/keyboard-return-icon.js +1 -1
  51. package/dist/es/components/layout/components/search/keyboard-shift-icon.js +1 -1
  52. package/dist/es/components/layout/components/search/keyboard.js +1 -1
  53. package/dist/es/components/layout/components/search/letter-s-icon.js +1 -1
  54. package/dist/es/components/layout/components/search/search-result-item.js +1 -1
  55. package/dist/es/components/layout/components/search/search-result.js +1 -1
  56. package/dist/es/components/layout/components/sidebar.js +1 -1
  57. package/dist/es/components/layout/components/tabs/context-menu.js +1 -1
  58. package/dist/es/components/layout/components/tabs/index.js +1 -1
  59. package/dist/es/components/layout/components/tabs/main-content-maximum.js +1 -1
  60. package/dist/es/components/layout/components/tabs/reload.js +1 -1
  61. package/dist/es/components/layout/components/tabs/tab-item.js +1 -1
  62. package/dist/es/components/layout/components/tabs/tab-list.js +1 -1
  63. package/dist/es/components/layout/components/tabs/tabs-container.js +1 -1
  64. package/dist/es/components/layout/components/theme-config/color-scheme-switcher.js +1 -1
  65. package/dist/es/components/layout/components/theme-config/color-scheme.js +1 -1
  66. package/dist/es/components/layout/components/theme-config/config-item.js +1 -1
  67. package/dist/es/components/layout/components/theme-config/index.js +1 -1
  68. package/dist/es/components/layout/components/theme-config/menu-layout-card.js +1 -1
  69. package/dist/es/components/layout/components/theme-config/menu-layout.js +1 -1
  70. package/dist/es/components/layout/components/theme-config/operations.js +1 -1
  71. package/dist/es/components/layout/components/theme-config/theme-color-picker.js +1 -1
  72. package/dist/es/components/layout/components/theme-config/theme-colors.js +1 -1
  73. package/dist/es/components/layout/hooks/index.js +1 -1
  74. package/dist/es/components/layout/hooks/use-color-scheme-updater.js +1 -1
  75. package/dist/es/components/layout/hooks/use-menu-navigate.js +1 -1
  76. package/dist/es/components/layout/hooks/use-mixed-menu.js +1 -1
  77. package/dist/es/components/layout/hooks/use-tab-navigate.js +1 -1
  78. package/dist/es/components/layout/index.js +1 -1
  79. package/dist/es/components/layout/store.js +1 -1
  80. package/dist/es/components/layout/styles.js +1 -1
  81. package/dist/es/components/login/challenge-outlet.js +57 -0
  82. package/dist/es/components/login/icon-login.js +1 -1
  83. package/dist/es/components/login/index.js +104 -199
  84. package/dist/es/components/login/password-change-challenge.js +1 -1
  85. package/dist/es/components/login/styles.js +1 -1
  86. package/dist/es/components/login/use-login-flow.js +104 -0
  87. package/dist/es/components/login/welcome-messages.js +1 -1
  88. package/dist/es/components/n-progress/components/bar.js +1 -1
  89. package/dist/es/components/n-progress/components/container.js +1 -1
  90. package/dist/es/components/n-progress/components/index.js +1 -1
  91. package/dist/es/components/n-progress/event.js +1 -1
  92. package/dist/es/components/n-progress/index.js +1 -1
  93. package/dist/es/components/not-found/index.js +1 -1
  94. package/dist/es/components/not-found/not-found-icon.js +1 -1
  95. package/dist/es/components/router-provider/context.js +1 -1
  96. package/dist/es/components/router-provider/index.js +1 -1
  97. package/dist/es/components/sso/index.js +47 -0
  98. package/dist/es/components/sso/styles.js +24 -0
  99. package/dist/es/components/sso/use-sso-login.js +48 -0
  100. package/dist/es/components/theme-config-provider/global-style.js +1 -1
  101. package/dist/es/components/theme-config-provider/index.js +1 -1
  102. package/dist/es/components/theme-config-provider/use-color-mode-effect.js +1 -1
  103. package/dist/es/components/theme-config-provider/use-theme-config.js +1 -1
  104. package/dist/es/constants/event.js +1 -1
  105. package/dist/es/constants/index.js +3 -3
  106. package/dist/es/constants/router.js +3 -3
  107. package/dist/es/constants/storage.js +1 -1
  108. package/dist/es/helpers/api.js +1 -1
  109. package/dist/es/helpers/app-version.js +1 -1
  110. package/dist/es/helpers/app.js +1 -1
  111. package/dist/es/helpers/auth.js +16 -9
  112. package/dist/es/helpers/event.js +1 -1
  113. package/dist/es/helpers/index.js +5 -5
  114. package/dist/es/helpers/menu-key.js +1 -1
  115. package/dist/es/helpers/query.js +1 -1
  116. package/dist/es/helpers/router.js +1 -1
  117. package/dist/es/hooks/index.js +1 -1
  118. package/dist/es/hooks/use-active-menu-key.js +1 -1
  119. package/dist/es/hooks/use-route-full-path.js +1 -1
  120. package/dist/es/index.js +23 -18
  121. package/dist/es/routes/access-denied.js +1 -1
  122. package/dist/es/routes/index.js +3 -2
  123. package/dist/es/routes/layout.js +1 -1
  124. package/dist/es/routes/login.js +8 -6
  125. package/dist/es/routes/root.js +1 -1
  126. package/dist/es/routes/sso.js +17 -0
  127. package/dist/es/stores/app.js +1 -1
  128. package/dist/es/stores/index.js +1 -1
  129. package/dist/es/stores/tab.js +1 -1
  130. package/dist/es/stores/theme.js +1 -1
  131. package/dist/types/components/index.d.ts +2 -1
  132. package/dist/types/components/login/challenge-outlet.d.ts +31 -0
  133. package/dist/types/components/login/index.d.ts +4 -2
  134. package/dist/types/components/login/payload.d.ts +40 -3
  135. package/dist/types/components/login/props.d.ts +25 -0
  136. package/dist/types/components/login/use-login-flow.d.ts +94 -0
  137. package/dist/types/components/sso/index.d.ts +42 -0
  138. package/dist/types/components/sso/styles.d.ts +3 -0
  139. package/dist/types/components/sso/use-sso-login.d.ts +95 -0
  140. package/dist/types/constants/index.d.ts +1 -1
  141. package/dist/types/constants/router.d.ts +2 -0
  142. package/dist/types/helpers/auth.d.ts +7 -0
  143. package/dist/types/helpers/index.d.ts +1 -1
  144. package/dist/types/index.d.ts +4 -4
  145. package/dist/types/routes/index.d.ts +2 -1
  146. package/dist/types/routes/login.d.ts +43 -2
  147. package/dist/types/routes/sso.d.ts +52 -0
  148. package/package.json +5 -5
@@ -1,4 +1,4 @@
1
- /*! @vef-framework-react/starter v2.16.0 made by Venus | 2026-08-18T09:26:25.543Z */
1
+ /*! @vef-framework-react/starter v2.17.0 made by Venus | 2026-08-20T14:31:41.073Z */
2
2
  import "../constants/router.js";
3
3
  import { useAppStore as e } from "../stores/app.js";
4
4
  import { Login as t } from "../components/login/index.js";
@@ -6,10 +6,7 @@ import { jsx as n } from "@emotion/react/jsx-runtime";
6
6
  import { redirect as r } from "@tanstack/react-router";
7
7
  import { z as i } from "@vef-framework-react/shared";
8
8
  //#region src/routes/login.tsx
9
- function a(a) {
10
- function o() {
11
- return /* @__PURE__ */ n(t, { ...a });
12
- }
9
+ function a(t) {
13
10
  return {
14
11
  validateSearch: i.object({ redirect: i.string().optional().default("/").catch("/") }),
15
12
  beforeLoad: ({ search: t }) => {
@@ -18,7 +15,12 @@ function a(a) {
18
15
  replace: !0
19
16
  });
20
17
  },
21
- component: o
18
+ component: o(t)
19
+ };
20
+ }
21
+ function o(e) {
22
+ return e.component ? e.component : function() {
23
+ return /* @__PURE__ */ n(t, { ...e });
22
24
  };
23
25
  }
24
26
  //#endregion
@@ -1,4 +1,4 @@
1
- /*! @vef-framework-react/starter v2.16.0 made by Venus | 2026-08-18T09:26:25.543Z */
1
+ /*! @vef-framework-react/starter v2.17.0 made by Venus | 2026-08-20T14:31:41.073Z */
2
2
  import { useAppStore as e } from "../stores/app.js";
3
3
  import { useActiveMenuKey as t } from "../hooks/use-active-menu-key.js";
4
4
  import { jsx as n } from "@emotion/react/jsx-runtime";
@@ -0,0 +1,17 @@
1
+ /*! @vef-framework-react/starter v2.17.0 made by Venus | 2026-08-20T14:31:41.073Z */
2
+ import { SsoLogin as e } from "../components/sso/index.js";
3
+ import { jsx as t } from "@emotion/react/jsx-runtime";
4
+ //#region src/routes/sso.tsx
5
+ function n(e) {
6
+ return {
7
+ validateSearch: (e) => e,
8
+ component: r(e)
9
+ };
10
+ }
11
+ function r(n) {
12
+ return n.component ? n.component : function() {
13
+ return /* @__PURE__ */ t(e, { ...n });
14
+ };
15
+ }
16
+ //#endregion
17
+ export { n as createSsoRouteOptions };
@@ -1,4 +1,4 @@
1
- /*! @vef-framework-react/starter v2.16.0 made by Venus | 2026-08-18T09:26:25.543Z */
1
+ /*! @vef-framework-react/starter v2.17.0 made by Venus | 2026-08-20T14:31:41.073Z */
2
2
  import { createPersistedStore as e } from "@vef-framework-react/core";
3
3
  //#region src/stores/app.ts
4
4
  var t = e(() => ({
@@ -1,4 +1,4 @@
1
- /*! @vef-framework-react/starter v2.16.0 made by Venus | 2026-08-18T09:26:25.543Z */
1
+ /*! @vef-framework-react/starter v2.17.0 made by Venus | 2026-08-20T14:31:41.073Z */
2
2
  import { useAppStore as e } from "./app.js";
3
3
  import { useTabStore as t } from "./tab.js";
4
4
  import { useThemeStore as n } from "./theme.js";
@@ -1,4 +1,4 @@
1
- /*! @vef-framework-react/starter v2.16.0 made by Venus | 2026-08-18T09:26:25.543Z */
1
+ /*! @vef-framework-react/starter v2.17.0 made by Venus | 2026-08-20T14:31:41.073Z */
2
2
  import "../constants/router.js";
3
3
  import { createPersistedStore as e, originalState as t } from "@vef-framework-react/core";
4
4
  //#region src/stores/tab.ts
@@ -1,4 +1,4 @@
1
- /*! @vef-framework-react/starter v2.16.0 made by Venus | 2026-08-18T09:26:25.543Z */
1
+ /*! @vef-framework-react/starter v2.17.0 made by Venus | 2026-08-20T14:31:41.073Z */
2
2
  import { createPersistedStore as e } from "@vef-framework-react/core";
3
3
  import { omit as t } from "@vef-framework-react/shared";
4
4
  //#region src/stores/theme.ts
@@ -3,8 +3,9 @@ export { App, type AppProps } from './app';
3
3
  export { BaseLayout, type BaseLayoutProps } from './base-layout';
4
4
  export { Error } from './error';
5
5
  export { Layout, type AppItem, type LayoutProps, type UserMenuItem } from './layout';
6
- export { Login, PASSWORD_CHANGE_CHALLENGE_TYPE, PasswordChangeChallenge, type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginParams, type LoginProps, type LoginResult, type PasswordChangeChallengeData, type PasswordChangeChallengeProps, type PasswordChangeChallengeSpec, type PasswordChangeReason, type PasswordLoginParams, type ResolveChallengeParams } from './login';
6
+ export { Login, LoginChallengeOutlet, PASSWORD_CHANGE_CHALLENGE_TYPE, PasswordChangeChallenge, useLoginFlow, type LoginChallenge, type LoginChallengeAutoResolver, type LoginChallengeAutoResolvers, type LoginChallengeOutletProps, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginFlow, type LoginParams, type LoginProps, type LoginResult, type PasswordChangeChallengeData, type PasswordChangeChallengeProps, type PasswordChangeChallengeSpec, type PasswordChangeReason, type PasswordLoginParams, type ResolveChallengeParams, type TrustCodeLoginParams, type UseLoginFlowOptions } from './login';
7
7
  export { NProgress, nProgressEventEmitter } from './n-progress';
8
8
  export { NotFound } from './not-found';
9
9
  export { RouterContextHookProvider, RouterProvider, type RouterProviderProps, type UseRouterContext } from './router-provider';
10
+ export { readTrustCodeHandoff, SSO_APP_ID_PARAM, SSO_CODE_PARAM, SsoLogin, useSsoLogin, type SsoHandoffSearch, type SsoLoginFlow, type SsoLoginProps, type UseSsoLoginOptions } from './sso';
10
11
  export { ThemeConfigProvider } from './theme-config-provider';
@@ -0,0 +1,31 @@
1
+ import { ReactNode, ReactPortal, ReactElement, JSXElementConstructor } from 'react';
2
+ import { LoginChallenge } from './payload';
3
+ import { LoginChallengeRenderers } from './props';
4
+ import { LoginFlow } from './use-login-flow';
5
+ export interface LoginChallengeOutletProps {
6
+ /**
7
+ * The flow whose pending challenge is presented. Nothing renders while the
8
+ * flow holds no challenge, so the outlet can sit unconditionally in a tree.
9
+ */
10
+ flow: LoginFlow;
11
+ /**
12
+ * One renderer per challenge type the backend may issue.
13
+ */
14
+ renderers?: LoginChallengeRenderers;
15
+ /**
16
+ * Presents a challenge no renderer is registered for. Defaults to an alert
17
+ * naming the type, which is what turns "the backend added a challenge the
18
+ * frontend has not caught up with" into a readable message instead of a
19
+ * blank screen.
20
+ */
21
+ fallback?: (challenge: LoginChallenge) => ReactNode;
22
+ }
23
+ /**
24
+ * Renders the challenge a login flow is waiting on, by looking up the renderer
25
+ * registered for its type.
26
+ *
27
+ * Every entry point that can meet a challenge needs this same lookup and the
28
+ * same answer for a type it does not know, so it lives here rather than inside
29
+ * any one login screen.
30
+ */
31
+ export declare function LoginChallengeOutlet({ flow, renderers, fallback }: LoginChallengeOutletProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("@emotion/react/jsx-runtime").JSX.Element | null | undefined;
@@ -1,5 +1,7 @@
1
1
  import { LoginProps } from './props';
2
2
  export declare function Login({ logo, title, description, publicKey, onLogin, onResolveChallenge, challengeRenderers }: LoginProps): import("@emotion/react/jsx-runtime").JSX.Element;
3
+ export { LoginChallengeOutlet, type LoginChallengeOutletProps } from './challenge-outlet';
3
4
  export { PASSWORD_CHANGE_CHALLENGE_TYPE, PasswordChangeChallenge, type PasswordChangeChallengeData, type PasswordChangeChallengeProps, type PasswordChangeChallengeSpec, type PasswordChangeReason } from './password-change-challenge';
4
- export { type LoginChallenge, type LoginParams, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './payload';
5
- export { type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginProps } from './props';
5
+ export { type LoginChallenge, type LoginParams, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams, type TrustCodeLoginParams } from './payload';
6
+ export { type LoginChallengeAutoResolver, type LoginChallengeAutoResolvers, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginProps } from './props';
7
+ export { useLoginFlow, type LoginFlow, type UseLoginFlowOptions } from './use-login-flow';
@@ -1,9 +1,34 @@
1
1
  import { AuthTokens } from '../../models';
2
- import { ResolvedChallenges } from '../../types/common';
2
+ import { Register, ResolvedChallenges } from '../../types/common';
3
3
  /**
4
- * The payload for login
4
+ * Login mechanisms the project adds beyond the framework's own. Augment
5
+ * `Register['loginParams']` with a union of payload shapes — an SMS code, a
6
+ * scanned QR ticket, a corporate directory handoff — and every login entry
7
+ * point accepts them without a cast.
8
+ *
9
+ * @example
10
+ * declare module "@vef-framework-react/starter" {
11
+ * interface Register {
12
+ * loginParams: { type: "sms"; principal: string; credentials: string };
13
+ * }
14
+ * }
15
+ */
16
+ type RegisteredLoginParams = Register extends {
17
+ loginParams: infer T extends BaseLoginParams;
18
+ } ? T : never;
19
+ /**
20
+ * The payload for login.
21
+ *
22
+ * Covers the two mechanisms the framework's backend ships with, plus whatever
23
+ * the project declared through `Register['loginParams']`.
24
+ *
25
+ * This is a union, where it once was the password shape alone. An `onLogin`
26
+ * annotated with `PasswordLoginParams` therefore no longer satisfies it — a
27
+ * parameter has to accept every mechanism the flow can send. Handlers that stay
28
+ * contextually typed by the prop are unaffected; one typed explicitly against
29
+ * the old meaning has to widen to `LoginParams` and narrow on `type`.
5
30
  */
6
- export type LoginParams = PasswordLoginParams;
31
+ export type LoginParams = PasswordLoginParams | TrustCodeLoginParams | RegisteredLoginParams;
7
32
  /**
8
33
  * The base payload for authentication
9
34
  */
@@ -30,6 +55,18 @@ export interface PasswordLoginParams extends BaseLoginParams<string> {
30
55
  */
31
56
  type: "password";
32
57
  }
58
+ /**
59
+ * The payload for single sign-on, exchanging the one-time code a trust-login
60
+ * gateway handed to the browser. `principal` is the app id that initiated the
61
+ * handoff; the gateway echoes it on the redirect so the exchange names the same
62
+ * application the code was issued for.
63
+ */
64
+ export interface TrustCodeLoginParams extends BaseLoginParams<string> {
65
+ /**
66
+ * The authentication type
67
+ */
68
+ type: "trust_code";
69
+ }
33
70
  /**
34
71
  * A challenge the user must complete during login (e.g., 2FA, department selection).
35
72
  *
@@ -71,6 +71,31 @@ export type LoginChallengeRenderer<K extends keyof ResolvedChallenges = keyof Re
71
71
  export type LoginChallengeRenderers = {
72
72
  [K in keyof ResolvedChallenges]: LoginChallengeRenderer<K>;
73
73
  };
74
+ /**
75
+ * Answers a single challenge type from data the page already holds, without
76
+ * showing it. Return `undefined` to decline and let the renderer present the
77
+ * challenge normally.
78
+ *
79
+ * Validate the answer against the challenge's own payload before returning it —
80
+ * `challenge.data` carries the options the server is willing to accept, and a
81
+ * pre-check keeps a stale value from spending an attempt against the backend's
82
+ * brute-force guard.
83
+ */
84
+ export type LoginChallengeAutoResolver<K extends keyof ResolvedChallenges = keyof ResolvedChallenges> = (challenge: Extract<LoginChallenge, {
85
+ type: K;
86
+ }>) => ResolvedChallenges[K]["response"] | undefined;
87
+ /**
88
+ * Auto-resolvers keyed by challenge type.
89
+ *
90
+ * Deliberately partial where `LoginChallengeRenderers` is exhaustive:
91
+ * presenting a challenge is mandatory, answering one on the user's behalf is
92
+ * opt-in per type. A challenge type absent here can never be resolved from
93
+ * ambient data — which is the point, since silently answering a second factor
94
+ * from a URL parameter would be a hole rather than a convenience.
95
+ */
96
+ export type LoginChallengeAutoResolvers = {
97
+ [K in keyof ResolvedChallenges]?: LoginChallengeAutoResolver<K>;
98
+ };
74
99
  /**
75
100
  * The shared subset of LoginProps, independent of whether the flow may
76
101
  * surface challenges.
@@ -0,0 +1,94 @@
1
+ import { LoginChallenge, LoginParams, LoginResult, ResolveChallengeParams } from './payload';
2
+ import { LoginChallengeAutoResolvers } from './props';
3
+ export interface UseLoginFlowOptions {
4
+ /**
5
+ * Submits credentials to the backend. Whatever it resolves with is fed
6
+ * straight into the flow, so a challenge and a completed authentication are
7
+ * handled by the same call site.
8
+ */
9
+ onLogin: (params: LoginParams) => Promise<LoginResult>;
10
+ /**
11
+ * Submits a challenge answer. Without it a challenge can be presented but
12
+ * never answered, so wire it whenever the backend may issue one.
13
+ */
14
+ onResolveChallenge?: (params: ResolveChallengeParams) => Promise<LoginResult>;
15
+ /**
16
+ * The public key for encrypting credentials. When present, the returned
17
+ * `encrypt` is available to the caller and to challenge renderers.
18
+ */
19
+ publicKey?: string;
20
+ /**
21
+ * Where to navigate once authentication completes. Defaults to the
22
+ * `redirect` search parameter, then to the index route.
23
+ */
24
+ redirectTo?: string;
25
+ /**
26
+ * Replaces the built-in post-authentication effect (navigation and the
27
+ * welcome notification). The session is written to the store before this
28
+ * runs — that part is the framework's own state contract and is never
29
+ * skipped, because the route guards read it.
30
+ */
31
+ onAuthenticated?: (result: LoginResult) => void | Promise<void>;
32
+ /**
33
+ * Answers selected challenges without showing them, keyed by challenge type.
34
+ * A resolver returning `undefined` leaves its challenge to be rendered
35
+ * normally, and each type is attempted at most once per flow: a silent
36
+ * answer the server rejects falls through to the renderer rather than
37
+ * retrying, which would loop and burn the account's lockout budget.
38
+ *
39
+ * Deliberately partial, unlike the renderer registry: presenting a challenge
40
+ * is mandatory, answering one on the user's behalf is opt-in per type. A
41
+ * type nobody declares here can never be resolved from ambient data.
42
+ */
43
+ autoResolve?: LoginChallengeAutoResolvers;
44
+ /**
45
+ * Receives the original rejection behind `error`. Useful for reporting;
46
+ * `error` remains the message to render.
47
+ */
48
+ onError?: (error: unknown) => void;
49
+ }
50
+ export interface LoginFlow {
51
+ /**
52
+ * Submits credentials. Resolves once the result has been applied — a
53
+ * challenge is now pending, or authentication completed and navigation ran.
54
+ * Never rejects: failures surface through `error`.
55
+ */
56
+ login: (params: LoginParams) => Promise<void>;
57
+ /**
58
+ * The challenge awaiting an answer, or `null` when credentials are being
59
+ * collected.
60
+ */
61
+ challenge: LoginChallenge | null;
62
+ /**
63
+ * Answers the pending challenge. Never rejects; failures surface through
64
+ * `error`. A no-op when no challenge is pending.
65
+ */
66
+ resolve: (response: unknown) => Promise<void>;
67
+ /**
68
+ * Abandons the pending challenge and returns to credential entry. The held
69
+ * challenge token is discarded, so the user must authenticate again. Ignored
70
+ * while `pending`: an answer already submitted will still be applied, so
71
+ * there is nothing left to abandon.
72
+ */
73
+ cancel: () => void;
74
+ /**
75
+ * Whether a login or challenge call is in flight. Calls made while it is
76
+ * true are ignored, so a double submit cannot start two attempts.
77
+ */
78
+ pending: boolean;
79
+ /**
80
+ * The message from the most recent failure, or `null`. Already localized and
81
+ * safe to render.
82
+ */
83
+ error: string | null;
84
+ /**
85
+ * Clears `error`.
86
+ */
87
+ clearError: () => void;
88
+ /**
89
+ * Encrypts a plaintext with the configured public key. Absent when no
90
+ * `publicKey` was given. May throw on an invalid key or empty input.
91
+ */
92
+ encrypt?: (plaintext: string) => string;
93
+ }
94
+ export declare function useLoginFlow({ onLogin, onResolveChallenge, publicKey, redirectTo, onAuthenticated, autoResolve, onError }: UseLoginFlowOptions): LoginFlow;
@@ -0,0 +1,42 @@
1
+ import { LoginResult, ResolveChallengeParams } from '../login/payload';
2
+ import { LoginChallengeRenderers } from '../login/props';
3
+ import { UseSsoLoginOptions } from './use-sso-login';
4
+ /**
5
+ * Challenge wiring for backends that issue them. A handoff runs the same
6
+ * challenge chain a password login does — the originating system authenticated
7
+ * the user, it did not satisfy this application's login policy.
8
+ */
9
+ interface SsoLoginPropsWithChallenge {
10
+ onResolveChallenge: (params: ResolveChallengeParams) => Promise<LoginResult>;
11
+ /**
12
+ * One renderer per challenge type the backend may issue.
13
+ */
14
+ challengeRenderers: LoginChallengeRenderers;
15
+ }
16
+ /**
17
+ * Single sign-on wiring for backends that never issue challenges.
18
+ */
19
+ interface SsoLoginPropsWithoutChallenge {
20
+ onResolveChallenge?: never;
21
+ challengeRenderers?: never;
22
+ }
23
+ /**
24
+ * The props of the SsoLogin component. Either both challenge hooks are wired up
25
+ * or neither is, exactly as for `<Login>`: renderers without a dispatcher put a
26
+ * challenge on screen whose submit button can never do anything, because
27
+ * `LoginFlow.resolve` is a no-op without `onResolveChallenge`.
28
+ */
29
+ export type SsoLoginProps = Omit<UseSsoLoginOptions, "onResolveChallenge"> & (SsoLoginPropsWithChallenge | SsoLoginPropsWithoutChallenge);
30
+ /**
31
+ * The default single sign-on landing page: it exchanges the handoff in the URL
32
+ * for a session, presents any challenge the exchange raises, and reports a
33
+ * failed handoff with a way back to the ordinary login.
34
+ *
35
+ * It is deliberately plain and takes no slots. An application that wants its
36
+ * own landing screen writes one over `useSsoLogin` and hands it to
37
+ * `createSsoRouteOptions` as `component` — that keeps the exchange, the
38
+ * one-time semantics and the challenge chain shared, while the presentation is
39
+ * entirely the application's.
40
+ */
41
+ export declare function SsoLogin({ challengeRenderers, ...options }: SsoLoginProps): import("@emotion/react/jsx-runtime").JSX.Element;
42
+ export { readTrustCodeHandoff, SSO_APP_ID_PARAM, SSO_CODE_PARAM, useSsoLogin, type SsoHandoffSearch, type SsoLoginFlow, type UseSsoLoginOptions } from './use-sso-login';
@@ -0,0 +1,3 @@
1
+ import { SerializedStyles } from '@emotion/serialize';
2
+ export declare const page: SerializedStyles;
3
+ export declare const panel: SerializedStyles;
@@ -0,0 +1,95 @@
1
+ import { LoginParams, LoginResult, ResolveChallengeParams } from '../login/payload';
2
+ import { LoginChallengeAutoResolvers } from '../login/props';
3
+ import { LoginFlow } from '../login/use-login-flow';
4
+ /**
5
+ * Query parameters of the framework's own trust-login handoff, as the gateway
6
+ * appends them to the redirect it sends the browser to.
7
+ */
8
+ export declare const SSO_APP_ID_PARAM = "app_id";
9
+ export declare const SSO_CODE_PARAM = "code";
10
+ /**
11
+ * The handoff's query parameters, exactly as the gateway left them. Values are
12
+ * whatever the URL carried, so a reader narrows before using one.
13
+ */
14
+ export type SsoHandoffSearch = Record<string, unknown>;
15
+ /**
16
+ * Reads the framework's trust-login handoff. Returns `undefined` when the link
17
+ * carries no usable one, which is reported as an invalid link rather than sent
18
+ * to the server.
19
+ */
20
+ export declare function readTrustCodeHandoff(search: SsoHandoffSearch): LoginParams | undefined;
21
+ export interface UseSsoLoginOptions {
22
+ /**
23
+ * Exchanges the handoff for a session. The same backend call an ordinary
24
+ * login uses — single sign-on is a credential type, not a separate endpoint.
25
+ */
26
+ onLogin: (params: LoginParams) => Promise<LoginResult>;
27
+ /**
28
+ * Submits a challenge answer. A handoff runs the full challenge chain, so
29
+ * wire it unless the backend cannot issue challenges.
30
+ */
31
+ onResolveChallenge?: (params: ResolveChallengeParams) => Promise<LoginResult>;
32
+ /**
33
+ * RSA public key for encrypting secrets a challenge collects, matching the
34
+ * `<Login>` prop. A handoff runs the same challenge chain as a password
35
+ * login, so a user whose password expired meets `password_change` here too —
36
+ * and without the key its renderer would submit the new password in clear
37
+ * text to a backend configured to expect it encrypted.
38
+ */
39
+ publicKey?: string;
40
+ /**
41
+ * Builds the exchange request from the handoff's query parameters. Returning
42
+ * `undefined` marks the link as invalid without calling the server.
43
+ * Defaults to the framework's trust-login convention.
44
+ */
45
+ readHandoff?: (search: SsoHandoffSearch) => LoginParams | undefined;
46
+ /**
47
+ * Where to navigate once the session is established. Defaults to the
48
+ * `redirect` search parameter, then to the index route.
49
+ */
50
+ redirectTo?: string;
51
+ /**
52
+ * Replaces the built-in post-authentication effect.
53
+ */
54
+ onAuthenticated?: (result: LoginResult) => void | Promise<void>;
55
+ /**
56
+ * Answers selected challenges from the handoff's own parameters. The usual
57
+ * case is a department the originating system already picked.
58
+ */
59
+ autoResolve?: LoginChallengeAutoResolvers;
60
+ /**
61
+ * Receives the original rejection behind `error`.
62
+ */
63
+ onError?: (error: unknown) => void;
64
+ }
65
+ export interface SsoLoginFlow extends LoginFlow {
66
+ /**
67
+ * What the page should be showing. `exchanging` also covers the frame before
68
+ * the exchange starts, so a landing page never renders an empty state.
69
+ */
70
+ status: "exchanging" | "challenge" | "failed";
71
+ /**
72
+ * The handoff's query parameters, snapshotted at mount. A custom landing page
73
+ * reads its own extra parameters from here, and a challenge auto-resolver
74
+ * reads the answers the link carried — both keep working after the address
75
+ * bar is cleaned, which the live router search does not: clearing the URL
76
+ * goes through `replaceState`, which `@tanstack/history` patches to notify
77
+ * the router, so its own search empties at that moment.
78
+ */
79
+ search: SsoHandoffSearch;
80
+ }
81
+ /**
82
+ * Exchanges a single sign-on handoff for a session, once per mount.
83
+ *
84
+ * The exchange is an ordinary login carrying a one-time code instead of a
85
+ * password, so everything after it — the challenge chain, token issuance, the
86
+ * store write, navigation — is the shared login flow. What is specific to a
87
+ * handoff is only what happens around it: reading the code out of the URL,
88
+ * spending it exactly once, and clearing it afterwards.
89
+ *
90
+ * Note what this deliberately does not do: it never short-circuits when a
91
+ * session already exists. A handoff may well arrive at an app the user is
92
+ * already signed into as somebody else, and bouncing them to the target page
93
+ * would silently keep the wrong identity.
94
+ */
95
+ export declare function useSsoLogin({ onLogin, onResolveChallenge, readHandoff, redirectTo, onAuthenticated, autoResolve, onError, publicKey }: UseSsoLoginOptions): SsoLoginFlow;
@@ -1,3 +1,3 @@
1
1
  export { ACCESS_DENIED_EVENT, UNAUTHENTICATED_EVENT } from './event';
2
- export { ACCESS_DENIED_ROUTE_ID, ACCESS_DENIED_ROUTE_PATH, INDEX_ROUTE_ID, INDEX_ROUTE_PATH, LOGIN_ROUTE_ID, LOGIN_ROUTE_PATH } from './router';
2
+ export { ACCESS_DENIED_ROUTE_ID, ACCESS_DENIED_ROUTE_PATH, INDEX_ROUTE_ID, INDEX_ROUTE_PATH, LOGIN_ROUTE_ID, LOGIN_ROUTE_PATH, SSO_ROUTE_ID, SSO_ROUTE_PATH } from './router';
3
3
  export { STORAGE_KEY_PREFIX_STORE, STORAGE_KEY_SUFFIX_STORE } from './storage';
@@ -1,5 +1,7 @@
1
1
  export declare const LOGIN_ROUTE_PATH = "/login";
2
2
  export declare const LOGIN_ROUTE_ID = "/_common/login";
3
+ export declare const SSO_ROUTE_PATH = "/sso";
4
+ export declare const SSO_ROUTE_ID = "/_common/sso";
3
5
  export declare const INDEX_ROUTE_PATH = "/";
4
6
  export declare const INDEX_ROUTE_ID = "/_layout";
5
7
  export declare const ACCESS_DENIED_ROUTE_PATH = "/access-denied";
@@ -1,2 +1,9 @@
1
1
  import { AnyRouter } from '@tanstack/react-router';
2
+ /**
3
+ * Drop the identity loaded for the previous session while leaving
4
+ * authentication state untouched. Called when a new session is established over
5
+ * an existing one, which single sign-on does by construction: the handoff
6
+ * arrives at an app the user may already be signed into as somebody else.
7
+ */
8
+ export declare function clearIdentityState(): void;
2
9
  export declare function handleClientLogout(router: AnyRouter): Promise<void>;
@@ -1,7 +1,7 @@
1
1
  export { createApiClient, type ApiClientOptions } from './api';
2
2
  export { createApp } from './app';
3
3
  export { setupAppVersionNotification, type AppChangelog, type AppVersionNotificationOptions } from './app-version';
4
- export { handleClientLogout } from './auth';
4
+ export { clearIdentityState, handleClientLogout } from './auth';
5
5
  export { dispatchCustomEvent, emitAccessDenied, emitUnauthenticated, onAccessDenied, onUnauthenticated } from './event';
6
6
  export { extractQueryParams, noopMutationFn } from './query';
7
7
  export { createRouter, type RouterOptions } from './router';
@@ -1,6 +1,6 @@
1
- export { PASSWORD_CHANGE_CHALLENGE_TYPE, PasswordChangeChallenge, type AppItem, type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginParams, type LoginProps, type LoginResult, type PasswordChangeChallengeData, type PasswordChangeChallengeProps, type PasswordChangeChallengeSpec, type PasswordChangeReason, type PasswordLoginParams, type ResolveChallengeParams, type UserMenuItem } from './components';
2
- export { ACCESS_DENIED_ROUTE_ID, ACCESS_DENIED_ROUTE_PATH, INDEX_ROUTE_ID, INDEX_ROUTE_PATH, LOGIN_ROUTE_ID, LOGIN_ROUTE_PATH } from './constants';
3
- export { createApiClient, createApp, createRouter, dispatchCustomEvent, emitAccessDenied, emitUnauthenticated, extractQueryParams, handleClientLogout, noopMutationFn, setupAppVersionNotification, type ApiClientOptions, type AppChangelog, type AppVersionNotificationOptions, type RouterOptions } from './helpers';
4
- export { createAccessDeniedRouteOptions, createLayoutRouteOptions, createLoginRouteOptions, createRootRouteOptions, type LayoutBeforeLoadArgs, type LayoutLoaderArgs } from './routes';
1
+ export { LoginChallengeOutlet, PASSWORD_CHANGE_CHALLENGE_TYPE, PasswordChangeChallenge, readTrustCodeHandoff, SSO_APP_ID_PARAM, SSO_CODE_PARAM, SsoLogin, useLoginFlow, useSsoLogin, type AppItem, type LoginChallenge, type LoginChallengeAutoResolver, type LoginChallengeAutoResolvers, type LoginChallengeOutletProps, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginFlow, type LoginParams, type LoginProps, type LoginResult, type PasswordChangeChallengeData, type PasswordChangeChallengeProps, type PasswordChangeChallengeSpec, type PasswordChangeReason, type PasswordLoginParams, type ResolveChallengeParams, type SsoHandoffSearch, type SsoLoginFlow, type SsoLoginProps, type TrustCodeLoginParams, type UseLoginFlowOptions, type UserMenuItem, type UseSsoLoginOptions } from './components';
2
+ export { ACCESS_DENIED_ROUTE_ID, ACCESS_DENIED_ROUTE_PATH, INDEX_ROUTE_ID, INDEX_ROUTE_PATH, LOGIN_ROUTE_ID, LOGIN_ROUTE_PATH, SSO_ROUTE_ID, SSO_ROUTE_PATH } from './constants';
3
+ export { clearIdentityState, createApiClient, createApp, createRouter, dispatchCustomEvent, emitAccessDenied, emitUnauthenticated, extractQueryParams, handleClientLogout, noopMutationFn, setupAppVersionNotification, type ApiClientOptions, type AppChangelog, type AppVersionNotificationOptions, type RouterOptions } from './helpers';
4
+ export { createAccessDeniedRouteOptions, createLayoutRouteOptions, createLoginRouteOptions, createRootRouteOptions, createSsoRouteOptions, type LayoutBeforeLoadArgs, type LayoutLoaderArgs, type LoginRouteOptions, type SsoRouteOptions } from './routes';
5
5
  export { useAppStore, useTabStore, useThemeStore, type AppState, type ColorScheme, type MenuLayoutMode, type Tab, type TabState, type ThemeColors, type ThemeState } from './stores';
6
6
  export type * from './types';
@@ -1,4 +1,5 @@
1
1
  export { createAccessDeniedRouteOptions } from './access-denied';
2
2
  export { createLayoutRouteOptions, type LayoutBeforeLoadArgs, type LayoutLoaderArgs } from './layout';
3
- export { createLoginRouteOptions } from './login';
3
+ export { createLoginRouteOptions, type LoginRouteOptions } from './login';
4
4
  export { createRootRouteOptions } from './root';
5
+ export { createSsoRouteOptions, type SsoRouteOptions } from './sso';
@@ -1,6 +1,46 @@
1
+ import { ReactNode } from 'react';
1
2
  import { LoginProps } from '../components';
2
3
  import { z } from '@vef-framework-react/shared';
3
- export declare function createLoginRouteOptions(props: LoginProps): {
4
+ /**
5
+ * Login route wiring that renders the framework's own page.
6
+ */
7
+ type LoginRouteOptionsWithDefaultPage = LoginProps & {
8
+ component?: never;
9
+ };
10
+ /**
11
+ * Login route wiring for a page the application supplies itself.
12
+ *
13
+ * Every prop of the default page is explicitly forbidden rather than merely
14
+ * absent. Excess-property checking would catch a fresh object literal on its
15
+ * own, but not a pre-built value — and there the surplus props are dropped in
16
+ * silence, which is the failure mode this union exists to prevent.
17
+ */
18
+ type LoginRouteOptionsWithCustomPage = Partial<Record<keyof LoginProps, never>> & {
19
+ /**
20
+ * Replaces the login page entirely. It renders inside this route, so it can
21
+ * call `useLoginFlow` to drive authentication — which is how an application
22
+ * gives login its own screen while keeping the redirect contract and the
23
+ * already-authenticated guard that live on the route rather than in the page.
24
+ */
25
+ component: () => ReactNode;
26
+ };
27
+ /**
28
+ * Options for the login route. Either the framework's page is configured, or
29
+ * the application supplies its own — a custom page wires `useLoginFlow` itself,
30
+ * so passing it alongside the default page's props would leave those props
31
+ * silently dead.
32
+ */
33
+ export type LoginRouteOptions = LoginRouteOptionsWithDefaultPage | LoginRouteOptionsWithCustomPage;
34
+ /**
35
+ * Route options for the login page.
36
+ *
37
+ * The route owns two things no login screen should have to restate: the
38
+ * `redirect` contract — where to return after authenticating, defaulted and
39
+ * `catch`-guarded so a malformed value cannot break the route — and the guard
40
+ * that sends an already-authenticated visitor straight there instead of showing
41
+ * them a login form.
42
+ */
43
+ export declare function createLoginRouteOptions(options: LoginRouteOptions): {
4
44
  readonly validateSearch: z.ZodObject<{
5
45
  redirect: z.ZodCatch<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
6
46
  }, z.core.$strip>;
@@ -9,5 +49,6 @@ export declare function createLoginRouteOptions(props: LoginProps): {
9
49
  redirect: string;
10
50
  };
11
51
  }) => void;
12
- readonly component: () => import("@emotion/react/jsx-runtime").JSX.Element;
52
+ readonly component: () => ReactNode;
13
53
  };
54
+ export {};
@@ -0,0 +1,52 @@
1
+ import { ReactNode } from 'react';
2
+ import { SsoLoginProps } from '../components';
3
+ /**
4
+ * Single sign-on route wiring that renders the framework's own landing page.
5
+ */
6
+ type SsoRouteOptionsWithDefaultPage = SsoLoginProps & {
7
+ component?: never;
8
+ };
9
+ /**
10
+ * Single sign-on route wiring for a landing page the application supplies.
11
+ *
12
+ * Every prop of the default page is explicitly forbidden rather than merely
13
+ * absent, for the same reason as on the login route: excess-property checking
14
+ * catches a fresh object literal but not a pre-built value, where the surplus
15
+ * props would be dropped in silence.
16
+ */
17
+ type SsoRouteOptionsWithCustomPage = Partial<Record<keyof SsoLoginProps, never>> & {
18
+ /**
19
+ * Replaces the landing page entirely. It renders inside this route, so it can
20
+ * call `useSsoLogin` to drive the exchange itself — which is how single
21
+ * sign-on gets an application-specific screen without reimplementing the
22
+ * one-time exchange or the challenge chain.
23
+ */
24
+ component: () => ReactNode;
25
+ };
26
+ /**
27
+ * Options for the single sign-on route. Either the framework's landing page is
28
+ * configured, or the application supplies its own — a custom page passes its
29
+ * own options to `useSsoLogin`, so accepting both would leave one set silently
30
+ * dead.
31
+ */
32
+ export type SsoRouteOptions = SsoRouteOptionsWithDefaultPage | SsoRouteOptionsWithCustomPage;
33
+ /**
34
+ * Route options for the single sign-on landing page — where a trust-login
35
+ * gateway redirects the browser after it verifies a handoff.
36
+ *
37
+ * Unlike `createLoginRouteOptions` there is deliberately no `beforeLoad` that
38
+ * bounces an already-authenticated visitor to their target. A handoff names the
39
+ * user it is for, and it may well arrive at a tab already signed in as somebody
40
+ * else; short-circuiting on the existing session would silently keep the wrong
41
+ * identity. The exchange runs regardless and replaces whatever session was
42
+ * there.
43
+ *
44
+ * The search parameters are passed through unvalidated because they are the
45
+ * originating system's contract, not this application's — `readHandoff` is
46
+ * where they are interpreted.
47
+ */
48
+ export declare function createSsoRouteOptions(options: SsoRouteOptions): {
49
+ readonly validateSearch: (search: Record<string, unknown>) => Record<string, unknown>;
50
+ readonly component: () => ReactNode;
51
+ };
52
+ export {};