Improve compatibility with hybrid mobile apps (#84)

Co-authored-by: Nick Nisi <nick.nisi@workos.com>

Author: vdsbenoit

src/create-client.test.ts

@@ -326,6 +326,94 @@ describe("create-client", () => {
       });
     });
 
+    describe("getSignInUrl", () => {
+      beforeEach(() => {
+        mockLocation();
+      });
+
+      afterEach(() => {
+        restoreLocation();
+      });
+
+      it("generates a PKCE challenge and returns the AuthKit sign-in page URL", async () => {
+        const { scope } = nockRefresh();
+        expect(sessionStorage.getItem(storageKeys.codeVerifier)).toBeNull();
+
+        client = await createClient("client_123abc", {
+          redirectUri: "https://example.com/",
+        });
+        const signInUrl = await client.getSignInUrl();
+        const url = new URL(signInUrl);
+
+        // Location.assign should not be called
+        expect(jest.mocked(location.assign)).not.toHaveBeenCalled();
+        expect({
+          url,
+          searchParams: Object.fromEntries(url.searchParams.entries()),
+        }).toEqual({
+          url: expect.objectContaining({
+            origin: "https://api.workos.com",
+            pathname: "/user_management/authorize",
+          }),
+          searchParams: {
+            client_id: "client_123abc",
+            code_challenge: expect.any(String),
+            code_challenge_method: "S256",
+            provider: "authkit",
+            redirect_uri: "https://example.com/",
+            response_type: "code",
+            screen_hint: "sign-in",
+          },
+        });
+        expect(sessionStorage.getItem(storageKeys.codeVerifier)).toBeDefined();
+        scope.done();
+      });
+    });
+
+    describe("getSignUpUrl", () => {
+      beforeEach(() => {
+        mockLocation();
+      });
+
+      afterEach(() => {
+        restoreLocation();
+      });
+
+      it("generates a PKCE challenge and returns the AuthKit sign-up page URL", async () => {
+        const { scope } = nockRefresh();
+        expect(sessionStorage.getItem(storageKeys.codeVerifier)).toBeNull();
+
+        client = await createClient("client_123abc", {
+          redirectUri: "https://example.com/",
+        });
+        const signUpUrl = await client.getSignUpUrl();
+        const url = new URL(signUpUrl);
+
+        // Location.assign should not be called
+        expect(jest.mocked(location.assign)).not.toHaveBeenCalled();
+        expect({
+          url,
+          searchParams: Object.fromEntries(url.searchParams.entries()),
+        }).toEqual({
+          url: expect.objectContaining({
+            origin: "https://api.workos.com",
+            pathname: "/user_management/authorize",
+          }),
+          searchParams: {
+            client_id: "client_123abc",
+            code_challenge: expect.any(String),
+            code_challenge_method: "S256",
+            provider: "authkit",
+            redirect_uri: "https://example.com/",
+            response_type: "code",
+            screen_hint: "sign-up",
+          },
+        });
+        expect(sessionStorage.getItem(storageKeys.codeVerifier)).toBeDefined();
+        scope.done();
+      });
+    });
+
     describe("signOut", () => {
       beforeEach(() => {
         mockLocation();
@@ -384,6 +472,92 @@ describe("create-client", () => {
         });
       });
 
+      describe("when the `navigate` option is set to false", () => {
+        it("makes a fetch request instead of redirecting", async () => {
+          const { scope } = nockRefresh();
+
+          client = await createClient("client_123abc", {
+            redirectUri: "https://example.com/",
+          });
+
+          const originalFetch = global.fetch;
+          const mockFetch = jest.fn().mockResolvedValue({
+            ok: true,
+          });
+          global.fetch = mockFetch;
+
+          try {
+            await client.signOut({ navigate: false });
+
+            // Location.assign should not be called
+            expect(jest.mocked(location.assign)).not.toHaveBeenCalled();
+
+            // Fetch should be called with the correct URL
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            const fetchUrl = new URL(mockFetch.mock.calls[0][0]);
+            expect({
+              fetchUrl,
+              searchParams: Object.fromEntries(fetchUrl.searchParams.entries()),
+            }).toEqual({
+              fetchUrl: expect.objectContaining({
+                origin: "https://api.workos.com",
+                pathname: "/user_management/sessions/logout",
+              }),
+              searchParams: { session_id: "session_123abc" },
+            });
+            scope.done();
+          } finally {
+            global.fetch = originalFetch;
+          }
+        });
+
+        it("includes the `returnTo` parameter", async () => {
+          const { scope } = nockRefresh();
+
+          client = await createClient("client_123abc", {
+            redirectUri: "https://example.com/",
+          });
+
+          const originalFetch = global.fetch;
+          const mockFetch = jest.fn().mockResolvedValue({
+            ok: true,
+          });
+          global.fetch = mockFetch;
+
+          try {
+            await client.signOut({
+              returnTo: "https://example.com",
+              navigate: false,
+            });
+
+            // Location.assign should not be called
+            expect(jest.mocked(location.assign)).not.toHaveBeenCalled();
+
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            const fetchUrl = new URL(mockFetch.mock.calls[0][0]);
+            expect({
+              fetchUrl,
+              searchParams: Object.fromEntries(fetchUrl.searchParams.entries()),
+            }).toEqual({
+              fetchUrl: expect.objectContaining({
+                origin: "https://api.workos.com",
+                pathname: "/user_management/sessions/logout",
+              }),
+              searchParams: {
+                session_id: "session_123abc",
+                return_to: "https://example.com",
+              },
+            });
+
+            scope.done();
+          } finally {
+            global.fetch = originalFetch;
+          }
+        });
+      });
+
       describe("when tokens are persisted in local storage in development", () => {
         it("clears the tokens", async () => {
           localStorage.setItem(storageKeys.refreshToken, "refresh_token");
@@ -398,6 +572,48 @@ describe("create-client", () => {
           expect(localStorage.getItem(storageKeys.refreshToken)).toBeNull();
           scope.done();
         });
+
+        describe("when `returnTo` is provided", () => {
+          it("clears the tokens", async () => {
+            localStorage.setItem(storageKeys.refreshToken, "refresh_token");
+            const { scope } = nockRefresh({ devMode: true });
+
+            client = await createClient("client_123abc", {
+              redirectUri: "https://example.com/",
+              devMode: true,
+            });
+            client.signOut({ returnTo: "https://example.com" });
+
+            expect(localStorage.getItem(storageKeys.refreshToken)).toBeNull();
+            scope.done();
+          });
+        });
+
+        describe("when the `navigate` is set to false", () => {
+          it("clears the tokens", async () => {
+            localStorage.setItem(storageKeys.refreshToken, "refresh_token");
+            const { scope } = nockRefresh({ devMode: true });
+
+            client = await createClient("client_123abc", {
+              redirectUri: "https://example.com/",
+              devMode: true,
+            });
+
+            const originalFetch = global.fetch;
+            const mockFetch = jest.fn().mockResolvedValue({
+              ok: true,
+            });
+            global.fetch = mockFetch;
+
+            try {
+              await client.signOut({ navigate: false });
+              expect(localStorage.getItem(storageKeys.refreshToken)).toBeNull();
+              scope.done();
+            } finally {
+              global.fetch = originalFetch;
+            }
+          });
+        });
       });
     });
 

src/create-client.ts

@@ -116,15 +116,32 @@ export class Client {
     }
   }
 
+  async getSignInUrl(opts: Omit<RedirectOptions, "type"> = {}) {
+    const url = await this.#getAuthorizationUrl({ ...opts, type: "sign-in" });
+    return url;
+  }
+
+  async getSignUpUrl(opts: Omit<RedirectOptions, "type"> = {}) {
+    const url = await this.#getAuthorizationUrl({ ...opts, type: "sign-up" });
+    return url;
+  }
+
   async signIn(opts: Omit<RedirectOptions, "type"> = {}) {
-    return this.#redirect({ ...opts, type: "sign-in" });
+    const url = await this.#getAuthorizationUrl({ ...opts, type: "sign-in" });
+    window.location.assign(url);
   }
 
   async signUp(opts: Omit<RedirectOptions, "type"> = {}) {
-    return this.#redirect({ ...opts, type: "sign-up" });
+    const url = await this.#getAuthorizationUrl({ ...opts, type: "sign-up" });
+    window.location.assign(url);
   }
 
-  signOut(options?: { returnTo: string }): void {
+  signOut(options?: { returnTo?: string; navigate?: true }): void;
+  signOut(options?: { returnTo?: string; navigate: false }): Promise<void>;
+  signOut(
+    options: { returnTo?: string; navigate?: boolean } = { navigate: true },
+  ): void | Promise<void> {
+    const navigate = options.navigate ?? true;
     const accessToken = memoryStorage.getItem(storageKeys.accessToken);
     if (typeof accessToken !== "string") return;
     const { sid: sessionId } = getClaims(accessToken);
@@ -136,7 +153,21 @@ export class Client {
 
     if (url) {
       removeSessionData({ devMode: this.#devMode });
-      window.location.assign(url);
+
+      if (navigate) {
+        window.location.assign(url);
+      } else {
+        return new Promise(async (resolve) => {
+          fetch(url, {
+            mode: "no-cors",
+            credentials: "include",
+          })
+            .catch((error) => {
+              console.warn("AuthKit: Failed to send logout request", error);
+            })
+            .finally(resolve);
+        });
+      }
     }
   }
 
@@ -382,7 +413,7 @@ An authorization_code was supplied for a login which did not originate at the ap
     }
   }
 
-  async #redirect({
+  async #getAuthorizationUrl({
     context,
     invitationToken,
     loginHint,
@@ -407,7 +438,7 @@ An authorization_code was supplied for a login which did not originate at the ap
       state: state ? JSON.stringify(state) : undefined,
     });
 
-    window.location.assign(url);
+    return url;
   }
 
   #getAccessToken() {

src/utils/is-redirect-callback.test.ts

@@ -16,11 +16,16 @@ describe("isRedirectCallback", () => {
 
   describe('when the given redirect URI ends with a "/"', () => {
     it("returns true when the current location otherwise matches without the slash", () => {
+      const originalPath = window.location.pathname;
+      window.history.replaceState({}, "", "/callback/");
+
       const redirectUri = "https://example.com/callback";
       const searchParams = new URLSearchParams(Object.entries({ code: "123" }));
 
       const result = isRedirectCallback(redirectUri, searchParams);
 
+      window.history.replaceState({}, "", originalPath);
+
       expect(result).toBe(true);
     });
   });
@@ -46,4 +51,66 @@ describe("isRedirectCallback", () => {
       expect(result).toBe(false);
     });
   });
+
+  describe("when using redirect URIs in hybrid mobile app (e.g. Capacitor)", () => {
+    /**
+     * These tests ensure the function works for hybrid apps built with Capacitor.
+     * For Android, the app uses http://localhost/callback as the current URL.
+     * For iOS, the app uses capacitor://localhost/callback as the current URL.
+     * See https://ionicframework.com/docs/troubleshooting/cors
+     * The redirectUri remains https://example.com/callback.
+     * In the mobile app context, and the redirectUri is deep linked towards the app.
+     */
+    it("returns true when current location is http://localhost/callback and redirectUri is https://example.com/callback (Android)", () => {
+      const originalLocation = window.location;
+      const androidLocation = new URL("http://localhost/callback");
+
+      delete (window as any).location;
+      Object.defineProperty(window, "location", {
+        value: androidLocation,
+        writable: true,
+        configurable: true,
+      });
+
+      const redirectUri = "https://example.com/callback";
+      const searchParams = new URLSearchParams(Object.entries({ code: "123" }));
+
+      const result = isRedirectCallback(redirectUri, searchParams);
+
+      delete (window as any).location;
+      Object.defineProperty(window, "location", {
+        value: originalLocation,
+        writable: true,
+        configurable: true,
+      });
+
+      expect(result).toBe(true);
+    });
+
+    it("returns true when current location is capacitor://localhost/callback and redirectUri is https://example.com/callback (iOS)", () => {
+      const originalLocation = window.location;
+      const iOSLocation = new URL("capacitor://localhost/callback");
+
+      delete (window as any).location;
+      Object.defineProperty(window, "location", {
+        value: iOSLocation,
+        writable: true,
+        configurable: true,
+      });
+
+      const redirectUri = "https://example.com/callback";
+      const searchParams = new URLSearchParams(Object.entries({ code: "123" }));
+
+      const result = isRedirectCallback(redirectUri, searchParams);
+
+      delete (window as any).location;
+      Object.defineProperty(window, "location", {
+        value: originalLocation,
+        writable: true,
+        configurable: true,
+      });
+
+      expect(result).toBe(true);
+    });
+  });
 });