@ahoo-wang/cosec-react 0.0.0-stage → 8.0.0-beta.1

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 (39) hide show
  1. package/README.md +89 -2
  2. package/README.zh-CN.md +71 -0
  3. package/dist/cosec/RefreshableRouteGuard.d.cts +9 -0
  4. package/dist/cosec/RefreshableRouteGuard.d.cts.map +1 -0
  5. package/dist/cosec/RefreshableRouteGuard.d.ts +9 -0
  6. package/dist/cosec/RefreshableRouteGuard.d.ts.map +1 -0
  7. package/dist/cosec/RouteGuard.d.cts +51 -0
  8. package/dist/cosec/RouteGuard.d.cts.map +1 -0
  9. package/dist/cosec/RouteGuard.d.ts +51 -0
  10. package/dist/cosec/RouteGuard.d.ts.map +1 -0
  11. package/dist/cosec/SecurityContext.d.cts +113 -0
  12. package/dist/cosec/SecurityContext.d.cts.map +1 -0
  13. package/dist/cosec/SecurityContext.d.ts +113 -0
  14. package/dist/cosec/SecurityContext.d.ts.map +1 -0
  15. package/dist/cosec/index.d.cts +5 -0
  16. package/dist/cosec/index.d.cts.map +1 -0
  17. package/dist/cosec/index.d.ts +5 -0
  18. package/dist/cosec/index.d.ts.map +1 -0
  19. package/dist/cosec/useSecurity.d.cts +119 -0
  20. package/dist/cosec/useSecurity.d.cts.map +1 -0
  21. package/dist/cosec/useSecurity.d.ts +119 -0
  22. package/dist/cosec/useSecurity.d.ts.map +1 -0
  23. package/dist/index.d.cts +2 -0
  24. package/dist/index.d.cts.map +1 -0
  25. package/dist/index.d.ts +2 -0
  26. package/dist/index.d.ts.map +1 -0
  27. package/dist/index.es.js +118 -0
  28. package/dist/index.es.js.map +1 -0
  29. package/dist/index.umd.cjs +2 -0
  30. package/dist/index.umd.cjs.map +1 -0
  31. package/dist/internal/useLatest.d.cts +14 -0
  32. package/dist/internal/useLatest.d.cts.map +1 -0
  33. package/dist/internal/useLatest.d.ts +14 -0
  34. package/dist/internal/useLatest.d.ts.map +1 -0
  35. package/dist/internal/useStoredToken.d.cts +15 -0
  36. package/dist/internal/useStoredToken.d.cts.map +1 -0
  37. package/dist/internal/useStoredToken.d.ts +15 -0
  38. package/dist/internal/useStoredToken.d.ts.map +1 -0
  39. package/package.json +91 -3
package/README.md CHANGED
@@ -1,3 +1,90 @@
1
- # Temporary Holding Version
1
+ # `@ahoo-wang/cosec-react`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ React hooks and components for an application that talks to CoSec through
4
+ [`@ahoo-wang/cosec-fetcher`](../cosec-fetcher/README.md): the signed-in state
5
+ of the user as React state, and route guards.
6
+
7
+ **Which CoSec it speaks.** CoSec 8.0 only, like `@ahoo-wang/cosec-fetcher`: it is
8
+ released with CoSec and reads the token pair the client stores. A CoSec 7 server
9
+ needs the hooks of `@ahoo-wang/fetcher-react` 6.x. Moving from those:
10
+ [Upgrading](#upgrading-from-ahoo-wangfetcher-react-6x).
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pnpm add react @ahoo-wang/fetcher @ahoo-wang/fetcher-eventbus \
16
+ @ahoo-wang/fetcher-storage @ahoo-wang/cosec-fetcher @ahoo-wang/cosec-react
17
+ ```
18
+
19
+ Until CoSec 8.0 is released these are pre-releases, which npm does not install
20
+ by default: use a dist-tag, `pnpm add @ahoo-wang/cosec-react@beta` (`@alpha`,
21
+ `@rc`), or an exact version. They are published with each CoSec release, at the
22
+ version of CoSec.
23
+
24
+ Peer dependencies: `react` (19) and `@ahoo-wang/cosec-fetcher`; the fetcher
25
+ packages are the client's (`cosec-fetcher`'s peers), and nothing else comes
26
+ with it. In particular it does not bring `@ahoo-wang/fetcher-react` or
27
+ `@ahoo-wang/fetcher-cosec`, the package `cosec-fetcher` replaces. The app must have exactly one copy of `@ahoo-wang/cosec-fetcher`: the hooks and
28
+ the client share the `TokenStorage` instance.
29
+
30
+ Requires Node `^22.12.0 || ^24.0.0 || >=26.0.0` to build.
31
+
32
+ ## Example
33
+
34
+ ```tsx
35
+ import {
36
+ RouteGuard,
37
+ SecurityProvider,
38
+ useSecurityContext,
39
+ } from '@ahoo-wang/cosec-react';
40
+ import { tokenStorage } from './tokenStorage';
41
+
42
+ function App() {
43
+ return (
44
+ <SecurityProvider
45
+ tokenStorage={tokenStorage}
46
+ onSignOut={() => window.location.assign('/login')}
47
+ >
48
+ <RouteGuard
49
+ fallback={<p>Please sign in</p>}
50
+ onUnauthorized={() => window.location.assign('/login')}
51
+ >
52
+ <Profile />
53
+ </RouteGuard>
54
+ </SecurityProvider>
55
+ );
56
+ }
57
+
58
+ function Profile() {
59
+ const { currentUser, signOut } = useSecurityContext();
60
+ return <button onClick={signOut}>Sign out {currentUser.sub}</button>;
61
+ }
62
+ ```
63
+
64
+ ## What is in it
65
+
66
+ - `SecurityProvider`, `useSecurityContext`, `SecurityContext`: the security
67
+ state of the page, from one `TokenStorage`.
68
+ - `useSecurity`: the same without the context.
69
+ - `RouteGuard`: renders its children for a signed-in user, otherwise the
70
+ `fallback`. `onUnauthorized` runs after the render commits, once each time the
71
+ user becomes (or starts out) not signed in.
72
+ - `RefreshableRouteGuard`: the same for a session that a `JwtTokenManager` can
73
+ refresh: it starts the refresh, shows `refreshing` while it runs, and shows
74
+ the `fallback` when the refresh fails.
75
+ - `ANONYMOUS_USER`: the `currentUser` of a visitor that is not signed in.
76
+
77
+ `authenticated` is the `TokenStorage`'s own answer for the stored token. The
78
+ guard is a convenience of the user interface, never the decision: CoSec decides
79
+ on the server.
80
+
81
+ ## Upgrading from `@ahoo-wang/fetcher-react` 6.x
82
+
83
+ - Import `SecurityProvider`, `useSecurity`, `useSecurityContext`, `RouteGuard`,
84
+ `RefreshableRouteGuard` and `ANONYMOUS_USER` from `@ahoo-wang/cosec-react`.
85
+ Nothing else changed in what they do: the code is the one of
86
+ `@ahoo-wang/fetcher-react` 6.1.0, which no longer needs to be installed for
87
+ them. `RouteGuard` and `RefreshableRouteGuard` return `ReactNode`, and
88
+ `CompositeTokenProvider`, the parameter of `signIn`, is exported.
89
+ - `@ahoo-wang/cosec-fetcher` replaces `@ahoo-wang/fetcher-cosec` (see its
90
+ README).
@@ -0,0 +1,71 @@
1
+ # `@ahoo-wang/cosec-react`
2
+
3
+ 面向通过 [`@ahoo-wang/cosec-fetcher`](../cosec-fetcher/README.zh-CN.md) 访问 CoSec 的应用的 React hooks 和组件:把用户的登录状态变成 React 状态,并提供路由守卫。
4
+
5
+ **对应哪个 CoSec。** 只对应 CoSec 8.0,与 `@ahoo-wang/cosec-fetcher` 一样:它随 CoSec 发布,读取客户端保存的令牌对。CoSec 7 服务端需要
6
+ `@ahoo-wang/fetcher-react` 6.x 里的这些 hooks。从那里迁移:[升级](#从-ahoo-wangfetcher-react-6x-升级)。
7
+
8
+ ## 安装
9
+
10
+ ```bash
11
+ pnpm add react @ahoo-wang/fetcher @ahoo-wang/fetcher-eventbus \
12
+ @ahoo-wang/fetcher-storage @ahoo-wang/cosec-fetcher @ahoo-wang/cosec-react
13
+ ```
14
+
15
+ CoSec 8.0 发布之前它们是预发布版本,npm 默认不会安装:用 dist-tag,`pnpm add @ahoo-wang/cosec-react@beta`(`@alpha`、`@rc`),或写明确切版本。
16
+ 它们随每次 CoSec 发布而发布,版本与 CoSec 相同。
17
+
18
+ 对等依赖:`react`(19)和 `@ahoo-wang/cosec-fetcher`;fetcher 的各个包是客户端(`cosec-fetcher` 的对等依赖)的,除此之外它不带任何别的东西。特别是它不会带上
19
+ `@ahoo-wang/fetcher-react`,也不会带上 `cosec-fetcher` 所取代的 `@ahoo-wang/fetcher-cosec`。
20
+ 应用里必须只有一份 `@ahoo-wang/cosec-fetcher`:hooks 和客户端共用同一个 `TokenStorage` 实例。
21
+
22
+ 构建需要 Node `^22.12.0 || ^24.0.0 || >=26.0.0`。
23
+
24
+ ## 示例
25
+
26
+ ```tsx
27
+ import {
28
+ RouteGuard,
29
+ SecurityProvider,
30
+ useSecurityContext,
31
+ } from '@ahoo-wang/cosec-react';
32
+ import { tokenStorage } from './tokenStorage';
33
+
34
+ function App() {
35
+ return (
36
+ <SecurityProvider
37
+ tokenStorage={tokenStorage}
38
+ onSignOut={() => window.location.assign('/login')}
39
+ >
40
+ <RouteGuard
41
+ fallback={<p>请先登录</p>}
42
+ onUnauthorized={() => window.location.assign('/login')}
43
+ >
44
+ <Profile />
45
+ </RouteGuard>
46
+ </SecurityProvider>
47
+ );
48
+ }
49
+
50
+ function Profile() {
51
+ const { currentUser, signOut } = useSecurityContext();
52
+ return <button onClick={signOut}>退出 {currentUser.sub}</button>;
53
+ }
54
+ ```
55
+
56
+ ## 里面有什么
57
+
58
+ - `SecurityProvider`、`useSecurityContext`、`SecurityContext`:页面的安全状态,来自一个 `TokenStorage`。
59
+ - `useSecurity`:不经过 context 的同一个 hook。
60
+ - `RouteGuard`:用户已登录时渲染子节点,否则渲染 `fallback`。`onUnauthorized` 在渲染提交之后运行,用户每次变为(或一开始就是)未登录时调用一次。
61
+ - `RefreshableRouteGuard`:用于 `JwtTokenManager` 能刷新的会话:它自己发起刷新,刷新期间渲染 `refreshing`,刷新失败时渲染 `fallback`。
62
+ - `ANONYMOUS_USER`:未登录访客的 `currentUser`。
63
+
64
+ `authenticated` 就是 `TokenStorage` 对所存令牌给出的答案。守卫只是界面上的便利,从来不是决定:决定在服务端由 CoSec 做出。
65
+
66
+ ## 从 `@ahoo-wang/fetcher-react` 6.x 升级
67
+
68
+ - 从 `@ahoo-wang/cosec-react` 导入 `SecurityProvider`、`useSecurity`、`useSecurityContext`、`RouteGuard`、`RefreshableRouteGuard` 和
69
+ `ANONYMOUS_USER`。它们做的事没有变化:代码就是 `@ahoo-wang/fetcher-react` 6.1.0 里的那一份,现在不必再为它们安装 `@ahoo-wang/fetcher-react`。`RouteGuard` 和
70
+ `RefreshableRouteGuard` 返回 `ReactNode`,`signIn` 的参数类型 `CompositeTokenProvider` 现在被导出。
71
+ - `@ahoo-wang/cosec-fetcher` 取代 `@ahoo-wang/fetcher-cosec`(见它的 README)。
@@ -0,0 +1,9 @@
1
+ import { RouteGuardProps } from './RouteGuard.cjs';
2
+ import { ReactNode } from 'react';
3
+ import { JwtTokenManager } from '@ahoo-wang/cosec-fetcher';
4
+ export interface RefreshableRouteGuardProps extends Omit<RouteGuardProps, 'onUnauthorized'> {
5
+ refreshing?: ReactNode;
6
+ tokenManager: JwtTokenManager;
7
+ }
8
+ export declare function RefreshableRouteGuard({ children, fallback, refreshing, tokenManager, }: RefreshableRouteGuardProps): ReactNode;
9
+ //# sourceMappingURL=RefreshableRouteGuard.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"RefreshableRouteGuard.d.cts","sourceRoot":"","sources":["../../src/cosec/RefreshableRouteGuard.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAGhE,MAAM,WAAW,0BAA2B,SAAQ,IAAI,CACtD,eAAe,EACf,gBAAgB,CACjB;IACC,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,YAAY,EAAE,eAAe,CAAC;CAC/B;AAED,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,YAAY,GACb,EAAE,0BAA0B,GAAG,SAAS,CAuCxC"}
@@ -0,0 +1,9 @@
1
+ import { RouteGuardProps } from './RouteGuard.js';
2
+ import { ReactNode } from 'react';
3
+ import { JwtTokenManager } from '@ahoo-wang/cosec-fetcher';
4
+ export interface RefreshableRouteGuardProps extends Omit<RouteGuardProps, 'onUnauthorized'> {
5
+ refreshing?: ReactNode;
6
+ tokenManager: JwtTokenManager;
7
+ }
8
+ export declare function RefreshableRouteGuard({ children, fallback, refreshing, tokenManager, }: RefreshableRouteGuardProps): ReactNode;
9
+ //# sourceMappingURL=RefreshableRouteGuard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"RefreshableRouteGuard.d.ts","sourceRoot":"","sources":["../../src/cosec/RefreshableRouteGuard.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAGhE,MAAM,WAAW,0BAA2B,SAAQ,IAAI,CACtD,eAAe,EACf,gBAAgB,CACjB;IACC,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,YAAY,EAAE,eAAe,CAAC;CAC/B;AAED,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,YAAY,GACb,EAAE,0BAA0B,GAAG,SAAS,CAuCxC"}
@@ -0,0 +1,51 @@
1
+ import { ReactNode } from 'react';
2
+ /**
3
+ * Props for the RouteGuard component.
4
+ */
5
+ export interface RouteGuardProps {
6
+ /**
7
+ * The content to render when the user is authenticated.
8
+ */
9
+ children: ReactNode;
10
+ /**
11
+ * The fallback content to render when the user is not authenticated.
12
+ * If not provided, nothing will be rendered.
13
+ */
14
+ fallback?: ReactNode;
15
+ /**
16
+ * Optional redirect function to call when user is not authenticated.
17
+ * This can be used to programmatically navigate to a login page. It runs
18
+ * after the render commits, once each time the user becomes (or starts
19
+ * out) unauthenticated — not during rendering.
20
+ */
21
+ onUnauthorized?: () => void;
22
+ }
23
+ /**
24
+ * Route guard component that conditionally renders content based on authentication status.
25
+ *
26
+ * This component uses the SecurityContext to check if the user is authenticated.
27
+ * If authenticated, it renders the children. If not authenticated, it renders the fallback
28
+ * content (if provided) and optionally calls the onUnauthorized callback.
29
+ *
30
+ * @param children - The protected content to render when authenticated.
31
+ * @param fallback - Optional fallback content to render when not authenticated.
32
+ * @param onUnauthorized - Optional callback to execute when user is not authenticated.
33
+ * @returns The children if authenticated, fallback if provided, or null otherwise.
34
+ * @example
35
+ * ```tsx
36
+ * import { RouteGuard } from '@ahoo-wang/cosec-react';
37
+ *
38
+ * function ProtectedPage() {
39
+ * return (
40
+ * <RouteGuard
41
+ * fallback={<div>Please log in to access this page.</div>}
42
+ * onUnauthorized={() => navigate('/login')}
43
+ * >
44
+ * <div>Protected content</div>
45
+ * </RouteGuard>
46
+ * );
47
+ * }
48
+ * ```
49
+ */
50
+ export declare function RouteGuard({ children, fallback, onUnauthorized, }: RouteGuardProps): ReactNode;
51
+ //# sourceMappingURL=RouteGuard.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"RouteGuard.d.cts","sourceRoot":"","sources":["../../src/cosec/RouteGuard.tsx"],"names":[],"mappings":"AAaA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,QAAQ,EACR,cAAc,GACf,EAAE,eAAe,GAAG,SAAS,CAiB7B"}
@@ -0,0 +1,51 @@
1
+ import { ReactNode } from 'react';
2
+ /**
3
+ * Props for the RouteGuard component.
4
+ */
5
+ export interface RouteGuardProps {
6
+ /**
7
+ * The content to render when the user is authenticated.
8
+ */
9
+ children: ReactNode;
10
+ /**
11
+ * The fallback content to render when the user is not authenticated.
12
+ * If not provided, nothing will be rendered.
13
+ */
14
+ fallback?: ReactNode;
15
+ /**
16
+ * Optional redirect function to call when user is not authenticated.
17
+ * This can be used to programmatically navigate to a login page. It runs
18
+ * after the render commits, once each time the user becomes (or starts
19
+ * out) unauthenticated — not during rendering.
20
+ */
21
+ onUnauthorized?: () => void;
22
+ }
23
+ /**
24
+ * Route guard component that conditionally renders content based on authentication status.
25
+ *
26
+ * This component uses the SecurityContext to check if the user is authenticated.
27
+ * If authenticated, it renders the children. If not authenticated, it renders the fallback
28
+ * content (if provided) and optionally calls the onUnauthorized callback.
29
+ *
30
+ * @param children - The protected content to render when authenticated.
31
+ * @param fallback - Optional fallback content to render when not authenticated.
32
+ * @param onUnauthorized - Optional callback to execute when user is not authenticated.
33
+ * @returns The children if authenticated, fallback if provided, or null otherwise.
34
+ * @example
35
+ * ```tsx
36
+ * import { RouteGuard } from '@ahoo-wang/cosec-react';
37
+ *
38
+ * function ProtectedPage() {
39
+ * return (
40
+ * <RouteGuard
41
+ * fallback={<div>Please log in to access this page.</div>}
42
+ * onUnauthorized={() => navigate('/login')}
43
+ * >
44
+ * <div>Protected content</div>
45
+ * </RouteGuard>
46
+ * );
47
+ * }
48
+ * ```
49
+ */
50
+ export declare function RouteGuard({ children, fallback, onUnauthorized, }: RouteGuardProps): ReactNode;
51
+ //# sourceMappingURL=RouteGuard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"RouteGuard.d.ts","sourceRoot":"","sources":["../../src/cosec/RouteGuard.tsx"],"names":[],"mappings":"AAaA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,QAAQ,EACR,cAAc,GACf,EAAE,eAAe,GAAG,SAAS,CAiB7B"}
@@ -0,0 +1,113 @@
1
+ import { UseSecurityOptions, UseSecurityReturn } from './useSecurity.cjs';
2
+ import { ReactNode } from 'react';
3
+ import { TokenStorage } from '@ahoo-wang/cosec-fetcher';
4
+ /**
5
+ * Type alias for the security context value, representing the authentication state and methods.
6
+ * This is equivalent to the return type of the useSecurity hook, providing reactive access to:
7
+ * - Current authenticated user information (JWT payload)
8
+ * - Authentication status (boolean flag)
9
+ * - Sign-in method for authenticating users
10
+ * - Sign-out method for clearing authentication
11
+ *
12
+ * Used internally by the SecurityContext to type the context value.
13
+ */
14
+ export type SecurityContextValue = UseSecurityReturn;
15
+ /**
16
+ * React context for managing authentication state across the component tree.
17
+ * This context enables sharing of authentication state and methods between components
18
+ * without prop drilling. Components can access authentication data and methods through
19
+ * the useSecurityContext hook when wrapped by the SecurityProvider.
20
+ *
21
+ * The context value is undefined by default, requiring components to be wrapped by
22
+ * SecurityProvider to access authentication functionality.
23
+ */
24
+ export declare const SecurityContext: import('react').Context<UseSecurityReturn | undefined>;
25
+ /**
26
+ * Configuration options for the SecurityProvider component.
27
+ * Extends UseSecurityOptions to include provider-specific settings like token storage and children.
28
+ */
29
+ export interface SecurityContextOptions extends UseSecurityOptions {
30
+ /**
31
+ * The token storage instance used to manage authentication tokens.
32
+ * This should be a valid TokenStorage implementation that handles token persistence,
33
+ * retrieval, and lifecycle management across different storage backends (localStorage,
34
+ * sessionStorage, memory, etc.).
35
+ */
36
+ tokenStorage: TokenStorage;
37
+ /**
38
+ * The child components that will have access to the security context.
39
+ * These components can use the useSecurityContext hook to access authentication state and methods.
40
+ */
41
+ children: ReactNode;
42
+ }
43
+ /**
44
+ * Provider component that supplies authentication state and methods to its child components.
45
+ * This component wraps the application or a portion of it to provide access to authentication
46
+ * functionality through the useSecurityContext hook. It internally uses the useSecurity hook
47
+ * to manage authentication state and makes it available via React context.
48
+ *
49
+ * @param tokenStorage - The token storage instance for managing authentication tokens.
50
+ * This should be a valid TokenStorage implementation that handles
51
+ * token persistence, retrieval, and lifecycle management across different
52
+ * storage backends (localStorage, sessionStorage, memory, etc.).
53
+ * @param children - The child components that will have access to the security context.
54
+ * These components can use the useSecurityContext hook to access authentication
55
+ * state and methods without prop drilling.
56
+ * @param useSecurityOptions - Optional configuration object containing lifecycle callbacks
57
+ * for sign-in and sign-out events. Extends UseSecurityOptions interface.
58
+ * @param useSecurityOptions.onSignIn - Callback function invoked when sign in is successful.
59
+ * @param useSecurityOptions.onSignOut - Callback function invoked when sign out occurs.
60
+ * @returns A React element that provides the security context to its children.
61
+ * The context value includes currentUser, authenticated status, signIn, and signOut methods.
62
+ * @throws {Error} May throw errors if tokenStorage operations fail during initialization,
63
+ * such as invalid tokens or storage access issues (implementation dependent).
64
+ * @example
65
+ * ```tsx
66
+ * import { SecurityProvider } from '@ahoo-wang/cosec-react';
67
+ * import { tokenStorage } from './tokenStorage';
68
+ * import { useNavigate } from 'react-router-dom';
69
+ *
70
+ * function App() {
71
+ * const navigate = useNavigate();
72
+ *
73
+ * return (
74
+ * <SecurityProvider
75
+ * tokenStorage={tokenStorage}
76
+ * onSignIn={() => navigate('/dashboard')}
77
+ * onSignOut={() => navigate('/login')}
78
+ * >
79
+ * <MyApp />
80
+ * </SecurityProvider>
81
+ * );
82
+ * }
83
+ * ```
84
+ */
85
+ export declare function SecurityProvider({ tokenStorage, children, ...useSecurityOptions }: SecurityContextOptions): import('react').JSX.Element;
86
+ /**
87
+ * Hook to access the security context within components wrapped by SecurityProvider.
88
+ * This hook provides reactive access to authentication state and methods throughout the component tree.
89
+ *
90
+ * @returns The security context containing currentUser, authenticated status, signIn, and signOut methods.
91
+ * @throws {Error} Throws an error if used outside of a SecurityProvider component.
92
+ * @example
93
+ * ```tsx
94
+ * import { useSecurityContext } from '@ahoo-wang/cosec-react';
95
+ *
96
+ * function UserProfile() {
97
+ * const { currentUser, authenticated, signOut } = useSecurityContext();
98
+ *
99
+ * if (!authenticated) {
100
+ * return <div>Please sign in</div>;
101
+ * }
102
+ *
103
+ * return (
104
+ * <div>
105
+ * <p>Welcome, {currentUser?.sub}!</p>
106
+ * <button onClick={signOut}>Sign Out</button>
107
+ * </div>
108
+ * );
109
+ * }
110
+ * ```
111
+ */
112
+ export declare function useSecurityContext(): SecurityContextValue;
113
+ //# sourceMappingURL=SecurityContext.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"SecurityContext.d.cts","sourceRoot":"","sources":["../../src/cosec/SecurityContext.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,wDAE3B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE;;;;;OAKG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,YAAY,EACZ,QAAQ,EACR,GAAG,kBAAkB,EACtB,EAAE,sBAAsB,+BAOxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,IAAI,oBAAoB,CAQzD"}
@@ -0,0 +1,113 @@
1
+ import { UseSecurityOptions, UseSecurityReturn } from './useSecurity.js';
2
+ import { ReactNode } from 'react';
3
+ import { TokenStorage } from '@ahoo-wang/cosec-fetcher';
4
+ /**
5
+ * Type alias for the security context value, representing the authentication state and methods.
6
+ * This is equivalent to the return type of the useSecurity hook, providing reactive access to:
7
+ * - Current authenticated user information (JWT payload)
8
+ * - Authentication status (boolean flag)
9
+ * - Sign-in method for authenticating users
10
+ * - Sign-out method for clearing authentication
11
+ *
12
+ * Used internally by the SecurityContext to type the context value.
13
+ */
14
+ export type SecurityContextValue = UseSecurityReturn;
15
+ /**
16
+ * React context for managing authentication state across the component tree.
17
+ * This context enables sharing of authentication state and methods between components
18
+ * without prop drilling. Components can access authentication data and methods through
19
+ * the useSecurityContext hook when wrapped by the SecurityProvider.
20
+ *
21
+ * The context value is undefined by default, requiring components to be wrapped by
22
+ * SecurityProvider to access authentication functionality.
23
+ */
24
+ export declare const SecurityContext: import('react').Context<UseSecurityReturn | undefined>;
25
+ /**
26
+ * Configuration options for the SecurityProvider component.
27
+ * Extends UseSecurityOptions to include provider-specific settings like token storage and children.
28
+ */
29
+ export interface SecurityContextOptions extends UseSecurityOptions {
30
+ /**
31
+ * The token storage instance used to manage authentication tokens.
32
+ * This should be a valid TokenStorage implementation that handles token persistence,
33
+ * retrieval, and lifecycle management across different storage backends (localStorage,
34
+ * sessionStorage, memory, etc.).
35
+ */
36
+ tokenStorage: TokenStorage;
37
+ /**
38
+ * The child components that will have access to the security context.
39
+ * These components can use the useSecurityContext hook to access authentication state and methods.
40
+ */
41
+ children: ReactNode;
42
+ }
43
+ /**
44
+ * Provider component that supplies authentication state and methods to its child components.
45
+ * This component wraps the application or a portion of it to provide access to authentication
46
+ * functionality through the useSecurityContext hook. It internally uses the useSecurity hook
47
+ * to manage authentication state and makes it available via React context.
48
+ *
49
+ * @param tokenStorage - The token storage instance for managing authentication tokens.
50
+ * This should be a valid TokenStorage implementation that handles
51
+ * token persistence, retrieval, and lifecycle management across different
52
+ * storage backends (localStorage, sessionStorage, memory, etc.).
53
+ * @param children - The child components that will have access to the security context.
54
+ * These components can use the useSecurityContext hook to access authentication
55
+ * state and methods without prop drilling.
56
+ * @param useSecurityOptions - Optional configuration object containing lifecycle callbacks
57
+ * for sign-in and sign-out events. Extends UseSecurityOptions interface.
58
+ * @param useSecurityOptions.onSignIn - Callback function invoked when sign in is successful.
59
+ * @param useSecurityOptions.onSignOut - Callback function invoked when sign out occurs.
60
+ * @returns A React element that provides the security context to its children.
61
+ * The context value includes currentUser, authenticated status, signIn, and signOut methods.
62
+ * @throws {Error} May throw errors if tokenStorage operations fail during initialization,
63
+ * such as invalid tokens or storage access issues (implementation dependent).
64
+ * @example
65
+ * ```tsx
66
+ * import { SecurityProvider } from '@ahoo-wang/cosec-react';
67
+ * import { tokenStorage } from './tokenStorage';
68
+ * import { useNavigate } from 'react-router-dom';
69
+ *
70
+ * function App() {
71
+ * const navigate = useNavigate();
72
+ *
73
+ * return (
74
+ * <SecurityProvider
75
+ * tokenStorage={tokenStorage}
76
+ * onSignIn={() => navigate('/dashboard')}
77
+ * onSignOut={() => navigate('/login')}
78
+ * >
79
+ * <MyApp />
80
+ * </SecurityProvider>
81
+ * );
82
+ * }
83
+ * ```
84
+ */
85
+ export declare function SecurityProvider({ tokenStorage, children, ...useSecurityOptions }: SecurityContextOptions): import('react').JSX.Element;
86
+ /**
87
+ * Hook to access the security context within components wrapped by SecurityProvider.
88
+ * This hook provides reactive access to authentication state and methods throughout the component tree.
89
+ *
90
+ * @returns The security context containing currentUser, authenticated status, signIn, and signOut methods.
91
+ * @throws {Error} Throws an error if used outside of a SecurityProvider component.
92
+ * @example
93
+ * ```tsx
94
+ * import { useSecurityContext } from '@ahoo-wang/cosec-react';
95
+ *
96
+ * function UserProfile() {
97
+ * const { currentUser, authenticated, signOut } = useSecurityContext();
98
+ *
99
+ * if (!authenticated) {
100
+ * return <div>Please sign in</div>;
101
+ * }
102
+ *
103
+ * return (
104
+ * <div>
105
+ * <p>Welcome, {currentUser?.sub}!</p>
106
+ * <button onClick={signOut}>Sign Out</button>
107
+ * </div>
108
+ * );
109
+ * }
110
+ * ```
111
+ */
112
+ export declare function useSecurityContext(): SecurityContextValue;
113
+ //# sourceMappingURL=SecurityContext.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"SecurityContext.d.ts","sourceRoot":"","sources":["../../src/cosec/SecurityContext.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,wDAE3B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE;;;;;OAKG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,YAAY,EACZ,QAAQ,EACR,GAAG,kBAAkB,EACtB,EAAE,sBAAsB,+BAOxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,IAAI,oBAAoB,CAQzD"}
@@ -0,0 +1,5 @@
1
+ export * from './SecurityContext.cjs';
2
+ export * from './useSecurity.cjs';
3
+ export * from './RouteGuard.cjs';
4
+ export * from './RefreshableRouteGuard.cjs';
5
+ //# sourceMappingURL=index.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/cosec/index.ts"],"names":[],"mappings":"AAaA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC"}
@@ -0,0 +1,5 @@
1
+ export * from './SecurityContext.js';
2
+ export * from './useSecurity.js';
3
+ export * from './RouteGuard.js';
4
+ export * from './RefreshableRouteGuard.js';
5
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cosec/index.ts"],"names":[],"mappings":"AAaA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC"}