@usehercules/auth 1.0.45 → 1.1.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.
@@ -5,10 +5,10 @@ import { ConvexProviderWithAuth, type ConvexReactClient } from "convex/react";
5
5
  import { jwtDecode } from "jwt-decode";
6
6
  import { useCallback, useMemo, useRef } from "react";
7
7
  import { useAuth } from "react-oidc-context";
8
+ import { withRefreshLock } from "../internal/refresh-lock";
8
9
  import type { HerculesAuthProvider } from "../react/HerculesAuthProvider";
9
10
 
10
11
  const REFRESH_THRESHOLD_MS = 60 * 60 * 1000; // 1 hour
11
- const LOCK_KEY = "__herculesAuthRefresh";
12
12
 
13
13
  function tokenExpiresWithin(token: string, ms: number): boolean {
14
14
  try {
@@ -19,56 +19,6 @@ function tokenExpiresWithin(token: string, ms: number): boolean {
19
19
  }
20
20
  }
21
21
 
22
- // Cross-tab mutex: uses Web Locks API when available, falls back to a
23
- // simple in-memory queue for environments that don't support it.
24
- async function withLock<T>(
25
- key: string,
26
- callback: () => Promise<T>,
27
- ): Promise<T> {
28
- if (typeof navigator !== "undefined" && navigator.locks) {
29
- return navigator.locks.request(key, callback);
30
- }
31
- return manualMutex(key, callback);
32
- }
33
-
34
- const mutexes = new Map<
35
- string,
36
- { running: Promise<void> | null; waiting: Array<() => Promise<void>> }
37
- >();
38
-
39
- async function manualMutex<T>(
40
- key: string,
41
- callback: () => Promise<T>,
42
- ): Promise<T> {
43
- return new Promise<T>((resolve, reject) => {
44
- const wrapped = () =>
45
- callback()
46
- .then(resolve)
47
- .catch(reject)
48
- .finally(() => {
49
- const mutex = mutexes.get(key)!;
50
- const next = mutex.waiting.shift();
51
- if (next) {
52
- mutex.running = next();
53
- } else {
54
- mutex.running = null;
55
- }
56
- });
57
-
58
- let mutex = mutexes.get(key);
59
- if (!mutex) {
60
- mutex = { running: null, waiting: [] };
61
- mutexes.set(key, mutex);
62
- }
63
-
64
- if (mutex.running === null) {
65
- mutex.running = wrapped();
66
- } else {
67
- mutex.waiting.push(wrapped);
68
- }
69
- });
70
- }
71
-
72
22
  function useUseAuthFromHercules() {
73
23
  const { isAuthenticated, user, isLoading, signinSilent } = useAuth();
74
24
  const idToken = user?.id_token;
@@ -98,7 +48,7 @@ function useUseAuthFromHercules() {
98
48
  if (inFlightRefresh.current) {
99
49
  return inFlightRefresh.current;
100
50
  }
101
- const refresh = withLock(LOCK_KEY, async () => {
51
+ const refresh = withRefreshLock(async () => {
102
52
  const tokenAfterLock = idTokenRef.current;
103
53
  if (
104
54
  tokenAfterLock != null &&
@@ -0,0 +1,50 @@
1
+ export const REFRESH_LOCK_KEY = "__herculesAuthRefresh";
2
+
3
+ type Queue = {
4
+ running: Promise<void> | null;
5
+ waiting: Array<() => Promise<void>>;
6
+ };
7
+
8
+ const mutexes = new Map<string, Queue>();
9
+
10
+ async function manualMutex<T>(
11
+ key: string,
12
+ callback: () => Promise<T>,
13
+ ): Promise<T> {
14
+ return new Promise<T>((resolve, reject) => {
15
+ const wrapped = () =>
16
+ callback()
17
+ .then(resolve)
18
+ .catch(reject)
19
+ .finally(() => {
20
+ const mutex = mutexes.get(key)!;
21
+ const next = mutex.waiting.shift();
22
+ if (next) {
23
+ mutex.running = next();
24
+ } else {
25
+ mutex.running = null;
26
+ }
27
+ });
28
+
29
+ let mutex = mutexes.get(key);
30
+ if (!mutex) {
31
+ mutex = { running: null, waiting: [] };
32
+ mutexes.set(key, mutex);
33
+ }
34
+
35
+ if (mutex.running === null) {
36
+ mutex.running = wrapped();
37
+ } else {
38
+ mutex.waiting.push(wrapped);
39
+ }
40
+ });
41
+ }
42
+
43
+ export async function withRefreshLock<T>(
44
+ callback: () => Promise<T>,
45
+ ): Promise<T> {
46
+ if (typeof navigator !== "undefined" && navigator.locks) {
47
+ return navigator.locks.request(REFRESH_LOCK_KEY, callback);
48
+ }
49
+ return manualMutex(REFRESH_LOCK_KEY, callback);
50
+ }
@@ -0,0 +1,372 @@
1
+ import { describe, it, expect, vi, beforeEach } from "vitest";
2
+ import {
3
+ act,
4
+ render,
5
+ screen,
6
+ waitFor,
7
+ configure,
8
+ } from "@testing-library/react";
9
+ import { HerculesAuthProvider } from "./HerculesAuthProvider.js";
10
+
11
+ configure({ reactStrictMode: false });
12
+
13
+ const mockSigninSilent = vi.fn();
14
+ const mockSigninRedirect = vi.fn();
15
+ const mockRemoveUser = vi.fn();
16
+ let mockAuthState: Record<string, unknown> = {};
17
+ const localStorageMock = createMemoryStorage();
18
+
19
+ Object.defineProperty(window, "localStorage", {
20
+ value: localStorageMock,
21
+ configurable: true,
22
+ });
23
+
24
+ vi.mock("react-oidc-context", () => ({
25
+ AuthProvider: ({ children }: { children: React.ReactNode }) => (
26
+ <>{children}</>
27
+ ),
28
+ useAuth: () => mockAuthState,
29
+ }));
30
+
31
+ vi.mock("oidc-client-ts", () => ({
32
+ UserManager: class {
33
+ constructor() {}
34
+ events = {
35
+ addAccessTokenExpiring: vi.fn(),
36
+ removeAccessTokenExpiring: vi.fn(),
37
+ };
38
+ signinSilent = vi.fn();
39
+ },
40
+ WebStorageStateStore: class {
41
+ constructor() {}
42
+ },
43
+ }));
44
+
45
+ vi.mock("../internal/refresh-lock", () => ({
46
+ withRefreshLock: <T,>(callback: () => Promise<T>) => callback(),
47
+ REFRESH_LOCK_KEY: "__herculesAuthRefresh",
48
+ }));
49
+
50
+ function setAuthState(overrides: Record<string, unknown>) {
51
+ mockAuthState = {
52
+ isLoading: false,
53
+ user: null,
54
+ signinSilent: mockSigninSilent,
55
+ ...overrides,
56
+ };
57
+ }
58
+
59
+ beforeEach(() => {
60
+ window.history.replaceState({}, "", "/");
61
+ window.localStorage.clear();
62
+ setAuthState({});
63
+ mockSigninSilent.mockReset();
64
+ mockSigninRedirect.mockReset();
65
+ mockRemoveUser.mockReset();
66
+ });
67
+
68
+ function renderProvider(
69
+ loadingFallback?: React.ReactNode,
70
+ children: React.ReactNode = <div data-testid="app">app content</div>,
71
+ ) {
72
+ return render(
73
+ <HerculesAuthProvider
74
+ authority="https://auth.example.com"
75
+ client_id="test-client"
76
+ loadingFallback={loadingFallback}
77
+ >
78
+ {children}
79
+ </HerculesAuthProvider>,
80
+ );
81
+ }
82
+
83
+ describe("HerculesAuthProvider accessTokenExpiring renewal listener", () => {
84
+ it("registers the lock-wrapped renewal listener by default", () => {
85
+ render(
86
+ <HerculesAuthProvider
87
+ authority="https://auth.example.com"
88
+ client_id="test-client"
89
+ >
90
+ <div data-testid="app">app</div>
91
+ </HerculesAuthProvider>,
92
+ );
93
+ expect(screen.getByTestId("app")).toBeDefined();
94
+ });
95
+
96
+ it("skips registering the listener when automaticSilentRenew is explicitly true", () => {
97
+ render(
98
+ <HerculesAuthProvider
99
+ authority="https://auth.example.com"
100
+ client_id="test-client"
101
+ userManagerSettings={{ automaticSilentRenew: true }}
102
+ >
103
+ <div data-testid="app">app</div>
104
+ </HerculesAuthProvider>,
105
+ );
106
+ expect(screen.getByTestId("app")).toBeDefined();
107
+ });
108
+ });
109
+
110
+ function createMemoryStorage(): Storage {
111
+ const store = new Map<string, string>();
112
+
113
+ return {
114
+ get length() {
115
+ return store.size;
116
+ },
117
+ clear() {
118
+ store.clear();
119
+ },
120
+ getItem(key: string) {
121
+ return store.get(key) ?? null;
122
+ },
123
+ key(index: number) {
124
+ return Array.from(store.keys())[index] ?? null;
125
+ },
126
+ removeItem(key: string) {
127
+ store.delete(key);
128
+ },
129
+ setItem(key: string, value: string) {
130
+ store.set(key, value);
131
+ },
132
+ };
133
+ }
134
+
135
+ describe("HerculesAuthProvider AuthRecoveryGate", () => {
136
+ it("prioritizes an impersonation handoff over expired-session recovery", async () => {
137
+ window.history.replaceState(
138
+ {},
139
+ "",
140
+ "/?hercules_impersonation_session_id=session_1&hercules_impersonation_token=token_1",
141
+ );
142
+ setAuthState({
143
+ isAuthenticated: true,
144
+ removeUser: mockRemoveUser.mockResolvedValue(undefined),
145
+ signinRedirect: mockSigninRedirect.mockResolvedValue(undefined),
146
+ user: { expired: true, id_token: "stale" },
147
+ });
148
+
149
+ renderProvider(<div data-testid="loading">loading</div>);
150
+
151
+ expect(screen.getByTestId("app")).toBeDefined();
152
+ expect(screen.queryByTestId("loading")).toBeNull();
153
+ await waitFor(() => {
154
+ expect(mockSigninRedirect).toHaveBeenCalledTimes(1);
155
+ });
156
+ expect(mockRemoveUser).toHaveBeenCalledTimes(1);
157
+ expect(mockSigninSilent).not.toHaveBeenCalled();
158
+ });
159
+
160
+ it("renders children (not loadingFallback) while isLoading is true", async () => {
161
+ setAuthState({ isLoading: true, user: null });
162
+ renderProvider(<div data-testid="loading">loading</div>);
163
+ expect(screen.getByTestId("app")).toBeDefined();
164
+ expect(screen.queryByTestId("loading")).toBeNull();
165
+ expect(mockSigninSilent).not.toHaveBeenCalled();
166
+ });
167
+
168
+ it("blocks children on the very first commit when user is already expired", () => {
169
+ mockSigninSilent.mockImplementation(() => new Promise<void>(() => {}));
170
+ setAuthState({
171
+ isLoading: false,
172
+ user: { expired: true, id_token: "stale" },
173
+ });
174
+ renderProvider(<div data-testid="loading">loading</div>);
175
+ expect(screen.getByTestId("loading")).toBeDefined();
176
+ expect(screen.queryByTestId("app")).toBeNull();
177
+ });
178
+
179
+ it("keeps the gate closed while signinSilent is in flight even if isLoading flips true", async () => {
180
+ let resolveSilent!: () => void;
181
+ mockSigninSilent.mockImplementation(
182
+ () =>
183
+ new Promise<void>((resolve) => {
184
+ resolveSilent = resolve;
185
+ }),
186
+ );
187
+ setAuthState({
188
+ isLoading: false,
189
+ user: { expired: true, id_token: "stale" },
190
+ });
191
+ const { rerender } = renderProvider(
192
+ <div data-testid="loading">loading</div>,
193
+ );
194
+ expect(screen.getByTestId("loading")).toBeDefined();
195
+ await waitFor(() => {
196
+ expect(mockSigninSilent).toHaveBeenCalledTimes(1);
197
+ });
198
+
199
+ setAuthState({
200
+ isLoading: true,
201
+ user: { expired: true, id_token: "stale" },
202
+ });
203
+ rerender(
204
+ <HerculesAuthProvider
205
+ authority="https://auth.example.com"
206
+ client_id="test-client"
207
+ loadingFallback={<div data-testid="loading">loading</div>}
208
+ >
209
+ <div data-testid="app">app content</div>
210
+ </HerculesAuthProvider>,
211
+ );
212
+ expect(screen.getByTestId("loading")).toBeDefined();
213
+ expect(screen.queryByTestId("app")).toBeNull();
214
+
215
+ await act(async () => {
216
+ resolveSilent();
217
+ });
218
+ await waitFor(() => {
219
+ expect(screen.getByTestId("app")).toBeDefined();
220
+ });
221
+ });
222
+
223
+ it("recovers correctly under React StrictMode (double-mount)", async () => {
224
+ configure({ reactStrictMode: true });
225
+ mockSigninSilent.mockResolvedValue(undefined);
226
+ setAuthState({ user: { expired: true, id_token: "stale" } });
227
+ renderProvider(<div data-testid="loading">loading</div>);
228
+ await waitFor(() => {
229
+ expect(screen.getByTestId("app")).toBeDefined();
230
+ });
231
+ configure({ reactStrictMode: false });
232
+ });
233
+
234
+ it("falls back to the outer timeout under StrictMode when signinSilent hangs", async () => {
235
+ configure({ reactStrictMode: true });
236
+ vi.useFakeTimers({ shouldAdvanceTime: true });
237
+ mockSigninSilent.mockImplementation(() => new Promise<void>(() => {}));
238
+ setAuthState({ user: { expired: true, id_token: "stale" } });
239
+ renderProvider(<div data-testid="loading">loading</div>);
240
+ expect(screen.getByTestId("loading")).toBeDefined();
241
+ await vi.advanceTimersByTimeAsync(10_000);
242
+ await waitFor(() => {
243
+ expect(screen.getByTestId("app")).toBeDefined();
244
+ });
245
+ vi.useRealTimers();
246
+ configure({ reactStrictMode: false });
247
+ });
248
+
249
+ it("releases the refresh lock at the safety deadline when signinSilent never settles", async () => {
250
+ vi.useFakeTimers({ shouldAdvanceTime: true });
251
+ mockSigninSilent.mockImplementation(() => new Promise<void>(() => {}));
252
+ setAuthState({ user: { expired: true, id_token: "stale" } });
253
+ renderProvider(<div data-testid="loading">loading</div>);
254
+ expect(screen.getByTestId("loading")).toBeDefined();
255
+ await vi.advanceTimersByTimeAsync(10_000);
256
+ await waitFor(() => {
257
+ expect(screen.getByTestId("app")).toBeDefined();
258
+ });
259
+ await vi.advanceTimersByTimeAsync(5_000);
260
+ await waitFor(() => {
261
+ expect(screen.getByTestId("app")).toBeDefined();
262
+ });
263
+ vi.useRealTimers();
264
+ });
265
+
266
+ it("renders children immediately when user is null", async () => {
267
+ setAuthState({ user: null });
268
+ renderProvider();
269
+ await waitFor(() => {
270
+ expect(screen.getByTestId("app")).toBeDefined();
271
+ });
272
+ expect(mockSigninSilent).not.toHaveBeenCalled();
273
+ });
274
+
275
+ it("renders children immediately when user is fresh (not expired)", async () => {
276
+ setAuthState({ user: { expired: false, id_token: "token" } });
277
+ renderProvider();
278
+ await waitFor(() => {
279
+ expect(screen.getByTestId("app")).toBeDefined();
280
+ });
281
+ expect(mockSigninSilent).not.toHaveBeenCalled();
282
+ });
283
+
284
+ it("calls signinSilent and renders loadingFallback when user is expired", async () => {
285
+ let resolveSilent!: () => void;
286
+ mockSigninSilent.mockImplementation(
287
+ () =>
288
+ new Promise<void>((resolve) => {
289
+ resolveSilent = resolve;
290
+ }),
291
+ );
292
+ setAuthState({ user: { expired: true, id_token: "stale" } });
293
+ renderProvider(<div data-testid="loading">loading</div>);
294
+ expect(screen.getByTestId("loading")).toBeDefined();
295
+ expect(screen.queryByTestId("app")).toBeNull();
296
+ await waitFor(() => {
297
+ expect(mockSigninSilent).toHaveBeenCalledTimes(1);
298
+ });
299
+ await act(async () => {
300
+ resolveSilent();
301
+ });
302
+ await waitFor(() => {
303
+ expect(screen.getByTestId("app")).toBeDefined();
304
+ });
305
+ });
306
+
307
+ it("renders children after the recovery times out", async () => {
308
+ vi.useFakeTimers({ shouldAdvanceTime: true });
309
+ mockSigninSilent.mockImplementation(() => new Promise<void>(() => {}));
310
+ setAuthState({ user: { expired: true, id_token: "stale" } });
311
+ renderProvider(<div data-testid="loading">loading</div>);
312
+ expect(screen.getByTestId("loading")).toBeDefined();
313
+ await vi.advanceTimersByTimeAsync(10_000);
314
+ await waitFor(() => {
315
+ expect(screen.getByTestId("app")).toBeDefined();
316
+ });
317
+ vi.useRealTimers();
318
+ });
319
+
320
+ it("renders children after signinSilent throws", async () => {
321
+ mockSigninSilent.mockRejectedValueOnce(new Error("nope"));
322
+ setAuthState({ user: { expired: true, id_token: "stale" } });
323
+ renderProvider(<div data-testid="loading">loading</div>);
324
+ await waitFor(() => {
325
+ expect(screen.getByTestId("app")).toBeDefined();
326
+ });
327
+ });
328
+
329
+ it("unblocks UI via outer timeout while keeping the lock held by in-flight signinSilent", async () => {
330
+ vi.useFakeTimers({ shouldAdvanceTime: true });
331
+ mockSigninSilent.mockImplementation(() => new Promise<void>(() => {}));
332
+ setAuthState({ user: { expired: true, id_token: "stale" } });
333
+ renderProvider(<div data-testid="loading">loading</div>);
334
+ expect(screen.getByTestId("loading")).toBeDefined();
335
+ await vi.advanceTimersByTimeAsync(10_000);
336
+ await waitFor(() => {
337
+ expect(screen.getByTestId("app")).toBeDefined();
338
+ });
339
+ vi.useRealTimers();
340
+ });
341
+
342
+ it("does not refire signinSilent on rerenders", async () => {
343
+ let resolveSilent!: () => void;
344
+ mockSigninSilent.mockImplementation(
345
+ () =>
346
+ new Promise<void>((resolve) => {
347
+ resolveSilent = resolve;
348
+ }),
349
+ );
350
+ setAuthState({ user: { expired: true, id_token: "stale" } });
351
+ const { rerender } = renderProvider();
352
+ await waitFor(() => {
353
+ expect(mockSigninSilent).toHaveBeenCalledTimes(1);
354
+ });
355
+ await act(async () => {
356
+ resolveSilent();
357
+ });
358
+ setAuthState({ user: { expired: true, id_token: "stale-2" } });
359
+ rerender(
360
+ <HerculesAuthProvider
361
+ authority="https://auth.example.com"
362
+ client_id="test-client"
363
+ >
364
+ <div data-testid="app">app content</div>
365
+ </HerculesAuthProvider>,
366
+ );
367
+ await waitFor(() => {
368
+ expect(screen.getByTestId("app")).toBeDefined();
369
+ });
370
+ expect(mockSigninSilent).toHaveBeenCalledTimes(1);
371
+ });
372
+ });