@inrupt/solid-client-authn-browser 1.13.4 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inrupt/solid-client-authn-browser",
-  "version": "1.13.4",
+  "version": "1.14.0",
   "license": "MIT",
   "types": "dist/index",
   "browser": "dist/index.js",
@@ -25,8 +25,8 @@
     "cross-fetch": "^3.1.5"
   },
   "dependencies": {
-    "@inrupt/oidc-client-ext": "^1.13.4",
-    "@inrupt/solid-client-authn-core": "^1.13.4",
+    "@inrupt/oidc-client-ext": "^1.14.0",
+    "@inrupt/solid-client-authn-core": "^1.14.0",
     "@types/lodash.clonedeep": "^4.5.6",
     "@types/node": "^18.0.3",
     "@types/uuid": "^9.0.1",
@@ -41,5 +41,5 @@
   "engines": {
     "node": "^14.0.0 || ^16.0.0"
   },
-  "gitHead": "ab437bbfb613f4f64b82b17e3a38177998a1762a"
+  "gitHead": "fcdfb264ec59cfbeb0e2821ddb7fb716450c13e2"
 }

package/src/Session.spec.ts

@@ -32,7 +32,7 @@ import { Session } from "./Session";
 import { LocalStorageMock } from "./storage/__mocks__/LocalStorage";
 import { mockSessionInfoManager } from "./sessionInfo/__mocks__/SessionInfoManager";
 import { KEY_CURRENT_SESSION, KEY_CURRENT_URL } from "./constant";
-import type ClientAuthentication from "./ClientAuthentication";
+import ClientAuthentication from "./ClientAuthentication";
 
 /* eslint-disable @typescript-eslint/ban-ts-comment */
 
@@ -408,19 +408,6 @@ describe("Session", () => {
     });
   });
 
-  describe("onError", () => {
-    it("calls the registered callback on error", async () => {
-      const onErrorCallback = jest.fn();
-      const mySession = new Session();
-      mySession.onError(onErrorCallback);
-      mySession.emit(EVENTS.ERROR, "error", "error_description");
-      expect(onErrorCallback).toHaveBeenCalledWith(
-        "error",
-        "error_description"
-      );
-    });
-  });
-
   describe("silent authentication", () => {
     it("does nothing if no previous session is available", async () => {
       mockLocalStorage({});
@@ -777,130 +764,271 @@ describe("Session", () => {
     });
   });
 
-  describe("onLogin", () => {
-    it("calls the registered callback on login", async () => {
-      const myCallback = jest.fn();
-      const clientAuthentication = mockClientAuthentication();
-      clientAuthentication.handleIncomingRedirect = (
-        jest.fn() as any
-      ).mockResolvedValue({
-        isLoggedIn: true,
-        sessionId: "a session ID",
-        webId: "https://some.webid#them",
+  describe("legacy events handlers", () => {
+    describe("onError", () => {
+      it("calls the registered callback on error", async () => {
+        const onErrorCallback = jest.fn();
+        const mySession = new Session();
+        mySession.onError(onErrorCallback);
+        mySession.emit(EVENTS.ERROR, "error", "error_description");
+        expect(onErrorCallback).toHaveBeenCalledWith(
+          "error",
+          "error_description"
+        );
       });
-      mockLocalStorage({});
-      const mySession = new Session({ clientAuthentication });
-      mySession.onLogin(myCallback);
-      await mySession.handleIncomingRedirect("https://some.url");
-      expect(myCallback).toHaveBeenCalled();
     });
 
-    it("does not call the registered callback if login isn't successful", async () => {
-      const failCallback = (): void => {
-        throw new Error(
-          "Should *NOT* call callback - this means test has failed!"
+    describe("onLogin", () => {
+      it("calls the registered callback on login", async () => {
+        const myCallback = jest.fn();
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = (
+          jest.fn() as any
+        ).mockResolvedValue({
+          isLoggedIn: true,
+          sessionId: "a session ID",
+          webId: "https://some.webid#them",
+        });
+        mockLocalStorage({});
+        const mySession = new Session({ clientAuthentication });
+        mySession.onLogin(myCallback);
+        await mySession.handleIncomingRedirect("https://some.url");
+        expect(myCallback).toHaveBeenCalled();
+      });
+
+      it("does not call the registered callback if login isn't successful", async () => {
+        const failCallback = (): void => {
+          throw new Error(
+            "Should *NOT* call callback - this means test has failed!"
+          );
+        };
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = jest.fn(
+          async (_url: string) => {
+            return {
+              isLoggedIn: false,
+              sessionId: "a session ID",
+              webId: "https://some.webid#them",
+            };
+          }
         );
-      };
-      const clientAuthentication = mockClientAuthentication();
-      clientAuthentication.handleIncomingRedirect = jest.fn(
-        async (_url: string) => {
-          return {
-            isLoggedIn: false,
-            sessionId: "a session ID",
-            webId: "https://some.webid#them",
-          };
-        }
-      );
-      const mySession = new Session({ clientAuthentication });
-      mySession.onLogin(failCallback);
-      await expect(
-        mySession.handleIncomingRedirect("https://some.url")
-      ).resolves.not.toThrow();
+        const mySession = new Session({ clientAuthentication });
+        mySession.onLogin(failCallback);
+        await expect(
+          mySession.handleIncomingRedirect("https://some.url")
+        ).resolves.not.toThrow();
+      });
+
+      it("sets the appropriate information before calling the callback", async () => {
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = jest.fn(
+          async (_url: string) => {
+            return {
+              isLoggedIn: true,
+              sessionId: "a session ID",
+              webId: "https://some.webid#them",
+            };
+          }
+        );
+        const mySession = new Session({ clientAuthentication });
+        const myCallback = jest.fn((): void => {
+          expect(mySession.info.webId).toBe("https://some.webid#them");
+        });
+        mySession.onLogin(myCallback);
+        await mySession.handleIncomingRedirect("https://some.url");
+        expect(myCallback).toHaveBeenCalled();
+        // Verify that the conditional assertion has been called
+        expect.assertions(2);
+      });
     });
 
-    it("sets the appropriate information before calling the callback", async () => {
-      const clientAuthentication = mockClientAuthentication();
-      clientAuthentication.handleIncomingRedirect = jest.fn(
-        async (_url: string) => {
-          return {
-            isLoggedIn: true,
-            sessionId: "a session ID",
-            webId: "https://some.webid#them",
-          };
-        }
-      );
-      const mySession = new Session({ clientAuthentication });
-      const myCallback = jest.fn((): void => {
-        expect(mySession.info.webId).toBe("https://some.webid#them");
+    describe("onLogout", () => {
+      it("calls the registered callback on logout", async () => {
+        const myCallback = jest.fn();
+        const mySession = new Session({
+          clientAuthentication: mockClientAuthentication(),
+        });
+
+        mySession.onLogout(myCallback);
+        await mySession.logout();
+        expect(myCallback).toHaveBeenCalled();
       });
-      mySession.onLogin(myCallback);
-      await mySession.handleIncomingRedirect("https://some.url");
-      expect(myCallback).toHaveBeenCalled();
-      // Verify that the conditional assertion has been called
-      expect.assertions(2);
     });
-  });
 
-  describe("onLogout", () => {
-    it("calls the registered callback on logout", async () => {
-      const myCallback = jest.fn();
-      const mySession = new Session({
-        clientAuthentication: mockClientAuthentication(),
+    describe("onSessionRestore", () => {
+      it("calls the registered callback on session restore", async () => {
+        // Set our window's location to our test value.
+        const defaultLocation = "https://coolSite.com/resource";
+        const currentLocation = "https://coolSite.com/redirect";
+
+        // This pretends we have previously triggered silent authentication and stored
+        // the location.
+        mockLocalStorage({
+          [KEY_CURRENT_URL]: defaultLocation,
+        });
+        // This acts as the URL the user has been redirected to.
+        mockLocation(currentLocation);
+        // This pretends the login is successful.
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = (
+          jest.fn() as any
+        ).mockResolvedValue({
+          isLoggedIn: true,
+          sessionId: "a session ID",
+          webId: "https://some.webid#them",
+        });
+
+        const mySession = new Session({
+          clientAuthentication,
+        });
+        const myCallback = (urlBeforeRestore: string): void => {
+          expect(urlBeforeRestore).toEqual(defaultLocation);
+        };
+
+        mySession.onSessionRestore(myCallback);
+        await mySession.handleIncomingRedirect(currentLocation);
+
+        // This verifies that the callback has been called
+        expect.assertions(1);
       });
+    });
 
-      mySession.onLogout(myCallback);
-      await mySession.logout();
-      expect(myCallback).toHaveBeenCalled();
+    describe("onSessionExpiration", () => {
+      it("calls the provided callback when receiving the appropriate event", async () => {
+        const myCallback = jest.fn();
+        const mySession = new Session({
+          clientAuthentication: mockClientAuthentication(),
+        });
+        mySession.onSessionExpiration(myCallback);
+        mySession.emit(EVENTS.SESSION_EXPIRED);
+        expect(myCallback).toHaveBeenCalled();
+      });
     });
   });
 
-  describe("onSessionRestore", () => {
-    it("calls the registered callback on session restore", async () => {
-      // Set our window's location to our test value.
-      const defaultLocation = "https://coolSite.com/resource";
-      const currentLocation = "https://coolSite.com/redirect";
+  describe("events.on", () => {
+    describe("login", () => {
+      it("calls the registered callback on login", async () => {
+        const myCallback = jest.fn();
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = jest
+          .fn<ClientAuthentication["handleIncomingRedirect"]>()
+          .mockResolvedValue({
+            isLoggedIn: true,
+            sessionId: "a session ID",
+            webId: "https://some.webid#them",
+          });
+        mockLocalStorage({});
+        const mySession = new Session({ clientAuthentication });
+        mySession.events.on(EVENTS.LOGIN, myCallback);
+        await mySession.handleIncomingRedirect("https://some.url");
+        expect(myCallback).toHaveBeenCalled();
+      });
 
-      // This pretends we have previously triggered silent authentication and stored
-      // the location.
-      mockLocalStorage({
-        [KEY_CURRENT_URL]: defaultLocation,
+      it("does not call the registered callback if login isn't successful", async () => {
+        const myCallback = jest.fn();
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = jest
+          .fn<ClientAuthentication["handleIncomingRedirect"]>()
+          .mockResolvedValue({
+            isLoggedIn: true,
+            sessionId: "a session ID",
+            webId: "https://some.webid#them",
+          });
+        const mySession = new Session({ clientAuthentication });
+        mySession.events.on(EVENTS.LOGIN, myCallback);
+        expect(myCallback).not.toHaveBeenCalled();
       });
-      // This acts as the URL the user has been redirected to.
-      mockLocation(currentLocation);
-      // This pretends the login is successful.
-      const clientAuthentication = mockClientAuthentication();
-      clientAuthentication.handleIncomingRedirect = (
-        jest.fn() as any
-      ).mockResolvedValue({
-        isLoggedIn: true,
-        sessionId: "a session ID",
-        webId: "https://some.webid#them",
+
+      it("sets the appropriate information before calling the callback", async () => {
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = jest
+          .fn<ClientAuthentication["handleIncomingRedirect"]>()
+          .mockResolvedValue({
+            isLoggedIn: true,
+            sessionId: "a session ID",
+            webId: "https://some.webid#them",
+          });
+        const mySession = new Session({ clientAuthentication });
+        const myCallback = jest.fn((): void => {
+          expect(mySession.info.webId).toBe("https://some.webid#them");
+        });
+        mySession.events.on(EVENTS.LOGIN, myCallback);
+        await mySession.handleIncomingRedirect("https://some.url");
+        expect(myCallback).toHaveBeenCalled();
+        // Verify that the conditional assertion has been called
+        expect.assertions(2);
       });
+    });
 
-      const mySession = new Session({
-        clientAuthentication,
+    describe("logout", () => {
+      it("calls the registered callback on logout", async () => {
+        const myCallback = jest.fn();
+        const mySession = new Session({
+          clientAuthentication: mockClientAuthentication(),
+        });
+
+        mySession.events.on(EVENTS.LOGOUT, myCallback);
+        await mySession.logout();
+        expect(myCallback).toHaveBeenCalled();
       });
-      const myCallback = (urlBeforeRestore: string): void => {
-        expect(urlBeforeRestore).toEqual(defaultLocation);
-      };
+    });
 
-      mySession.onSessionRestore(myCallback);
-      await mySession.handleIncomingRedirect(currentLocation);
+    describe("sessionRestore", () => {
+      it("calls the registered callback on session restore", async () => {
+        // Set our window's location to our test value.
+        const defaultLocation = "https://coolSite.com/resource";
+        const currentLocation = "https://coolSite.com/redirect";
 
-      // This verifies that the callback has been called
-      expect.assertions(1);
+        // This pretends we have previously triggered silent authentication and stored
+        // the location.
+        mockLocalStorage({
+          [KEY_CURRENT_URL]: defaultLocation,
+        });
+        // This acts as the URL the user has been redirected to.
+        mockLocation(currentLocation);
+        // This pretends the login is successful.
+        const clientAuthentication = mockClientAuthentication();
+        clientAuthentication.handleIncomingRedirect = jest
+          .fn<ClientAuthentication["handleIncomingRedirect"]>()
+          .mockResolvedValue({
+            isLoggedIn: true,
+            sessionId: "a session ID",
+            webId: "https://some.webid#them",
+          });
+
+        const mySession = new Session({
+          clientAuthentication,
+        });
+        const myCallback = (urlBeforeRestore: string): void => {
+          expect(urlBeforeRestore).toEqual(defaultLocation);
+        };
+
+        mySession.events.on(EVENTS.SESSION_RESTORED, myCallback);
+        await mySession.handleIncomingRedirect(currentLocation);
+
+        // This verifies that the callback has been called
+        expect.assertions(1);
+      });
     });
   });
 
-  describe("onSessionExpiration", () => {
-    it("calls the provided callback when receiving the appropriate event", async () => {
-      const myCallback = jest.fn();
-      const mySession = new Session({
-        clientAuthentication: mockClientAuthentication(),
-      });
-      mySession.onSessionExpiration(myCallback);
-      mySession.emit(EVENTS.SESSION_EXPIRED);
-      expect(myCallback).toHaveBeenCalled();
+  describe("proxies events to the session", () => {
+    // This describe block is only required as long as Session extends the EventEmitter
+    // class.
+    it("proxies the EventEmitter calls from events to the session object", () => {
+      const mySession = new Session();
+      const spiedOn = jest.spyOn(mySession, "on");
+      mySession.events.on("login", jest.fn());
+      expect(spiedOn).toHaveBeenCalled();
+    });
+
+    it("throws on calls from events which aren't part of the EventEmitter interface", () => {
+      const mySession = new Session();
+      // @ts-expect-error onLogin is a function on Session, and not SessionEventEmitter
+      expect(() => mySession.events.onLogin(jest.fn())).toThrow(
+        "[onLogin] is not supported"
+      );
     });
   });
 });

package/src/Session.ts

@@ -22,14 +22,17 @@
 /**
  * @hidden
  */
-import { EventEmitter } from "events";
 import {
   EVENTS,
   ILoginInputOptions,
   ISessionInfo,
   IStorage,
+  IHasSessionEventListener,
+  ISessionEventListener,
+  buildProxyHandler,
 } from "@inrupt/solid-client-authn-core";
 import { v4 } from "uuid";
+import EventEmitter from "events";
 import ClientAuthentication from "./ClientAuthentication";
 import { getClientAuthenticationWithDependencies } from "./dependencies";
 import { KEY_CURRENT_SESSION, KEY_CURRENT_URL } from "./constant";
@@ -116,7 +119,7 @@ export async function silentlyAuthenticate(
         clientSecret: storedSessionInfo.clientAppSecret,
         tokenType: storedSessionInfo.tokenType ?? "DPoP",
       },
-      session
+      session.events
     );
     return true;
   }
@@ -132,12 +135,19 @@ function isLoggedIn(
 /**
  * A {@link Session} object represents a user's session on an application. The session holds state, as it stores information enabling acces to private resources after login for instance.
  */
-export class Session extends EventEmitter {
+export class Session extends EventEmitter implements IHasSessionEventListener {
   /**
    * Information regarding the current session.
    */
   public readonly info: ISessionInfo;
 
+  /**
+   * Session attribute exposing the EventEmitter interface, to listen on session
+   * events such as login, logout, etc.
+   * @since 1.15.0
+   */
+  public readonly events: ISessionEventListener;
+
   private clientAuthentication: ClientAuthentication;
 
   private tokenRequestInProgress = false;
@@ -162,7 +172,17 @@ export class Session extends EventEmitter {
     sessionId: string | undefined = undefined
   ) {
     super();
-
+    // Until Session no longer implements EventEmitter, this.events is just a proxy
+    // to this (with some interface filtering). When we make the breaking change,
+    // this.events will be a regular EventEmitter (implementing ISessionEventEmitter):
+    // this.events = new EventEmitter();
+    this.events = new Proxy(
+      this,
+      buildProxyHandler(
+        Session.prototype,
+        "events only implements ISessionEventListener"
+      )
+    );
     if (sessionOptions.clientAuthentication) {
       this.clientAuthentication = sessionOptions.clientAuthentication;
     } else if (sessionOptions.secureStorage && sessionOptions.insecureStorage) {
@@ -191,13 +211,13 @@ export class Session extends EventEmitter {
     // enable silent refresh. The current session ID specifically stored in 'localStorage'
     // (as opposed to using our storage abstraction layer) because it is only
     // used in a browser-specific mechanism.
-    this.on(EVENTS.LOGIN, () =>
+    this.events.on(EVENTS.LOGIN, () =>
       window.localStorage.setItem(KEY_CURRENT_SESSION, this.info.sessionId)
     );
 
-    this.on(EVENTS.SESSION_EXPIRED, () => this.internalLogout(false));
+    this.events.on(EVENTS.SESSION_EXPIRED, () => this.internalLogout(false));
 
-    this.on(EVENTS.ERROR, () => this.internalLogout(false));
+    this.events.on(EVENTS.ERROR, () => this.internalLogout(false));
   }
 
   /**
@@ -216,7 +236,7 @@ export class Session extends EventEmitter {
         // Defaults the token type to DPoP
         tokenType: options.tokenType ?? "DPoP",
       },
-      this
+      this.events
     );
     // `login` redirects the user away from the app,
     // so unless it throws an error, there is no code that should run afterwards
@@ -250,7 +270,7 @@ export class Session extends EventEmitter {
     await this.clientAuthentication.logout(this.info.sessionId);
     this.info.isLoggedIn = false;
     if (emitSignal) {
-      this.emit(EVENTS.LOGOUT);
+      (this.events as EventEmitter).emit(EVENTS.LOGOUT);
     }
   };
 
@@ -282,7 +302,7 @@ export class Session extends EventEmitter {
     this.tokenRequestInProgress = true;
     const sessionInfo = await this.clientAuthentication.handleIncomingRedirect(
       url,
-      this
+      this.events
     );
     if (isLoggedIn(sessionInfo)) {
       this.setSessionInfo(sessionInfo);
@@ -290,13 +310,13 @@ export class Session extends EventEmitter {
       if (currentUrl === null) {
         // The login event can only be triggered **after** the user has been
         // redirected from the IdP with access and ID tokens.
-        this.emit(EVENTS.LOGIN);
+        (this.events as EventEmitter).emit(EVENTS.LOGIN);
       } else {
         // If an URL is stored in local storage, we are being logged in after a
         // silent authentication, so remove our currently stored URL location
         // to clean up our state now that we are completing the re-login process.
         window.localStorage.removeItem(KEY_CURRENT_URL);
-        this.emit(EVENTS.SESSION_RESTORED, currentUrl);
+        (this.events as EventEmitter).emit(EVENTS.SESSION_RESTORED, currentUrl);
       }
     } else if (options.restorePreviousSession === true) {
       // Silent authentication happens after a refresh, which means there are no
@@ -332,18 +352,20 @@ export class Session extends EventEmitter {
    * The callback is called when {@link handleIncomingRedirect} completes successfully.
    *
    * @param callback The function called when a user completes login.
+   * @deprecated Prefer session.events.on(EVENTS.LOGIN, callback)
    */
   onLogin(callback: () => unknown): void {
-    this.on(EVENTS.LOGIN, callback);
+    this.events.on(EVENTS.LOGIN, callback);
   }
 
   /**
    * Register a callback function to be called when a user logs out:
    *
    * @param callback The function called when a user completes logout.
+   * @deprecated Prefer session.events.on(EVENTS.LOGOUT, callback)
    */
   onLogout(callback: () => unknown): void {
-    this.on(EVENTS.LOGOUT, callback);
+    this.events.on(EVENTS.LOGOUT, callback);
   }
 
   /**
@@ -351,6 +373,7 @@ export class Session extends EventEmitter {
    *
    * @param callback The function called when an error occurs.
    * @since 1.11.0
+   * @deprecated Prefer session.events.on(EVENTS.ERROR, callback)
    */
   onError(
     callback: (
@@ -358,7 +381,7 @@ export class Session extends EventEmitter {
       errorDescription?: string | null
     ) => unknown
   ): void {
-    this.on(EVENTS.ERROR, callback);
+    this.events.on(EVENTS.ERROR, callback);
   }
 
   /**
@@ -368,9 +391,10 @@ export class Session extends EventEmitter {
    * at the time the session was restored.
    *
    * @param callback The function called when a user's already logged-in session is restored, e.g., after a silent authentication is completed after a page refresh.
+   * @deprecated Prefer session.events.on(EVENTS.SESSION_RESTORED, callback)
    */
   onSessionRestore(callback: (currentUrl: string) => unknown): void {
-    this.on(EVENTS.SESSION_RESTORED, callback);
+    this.events.on(EVENTS.SESSION_RESTORED, callback);
   }
 
   /**
@@ -378,9 +402,10 @@ export class Session extends EventEmitter {
    * make authenticated requests, but following a user logout.
    * @param callback The function that runs on session expiration.
    * @since 1.11.0
+   * @deprecated Prefer session.events.on(EVENTS.SESSION_EXPIRED, callback)
    */
   onSessionExpiration(callback: () => unknown): void {
-    this.on(EVENTS.SESSION_EXPIRED, callback);
+    this.events.on(EVENTS.SESSION_EXPIRED, callback);
   }
 
   private setSessionInfo(
@@ -390,7 +415,7 @@ export class Session extends EventEmitter {
     this.info.webId = sessionInfo.webId;
     this.info.sessionId = sessionInfo.sessionId;
     this.info.expirationDate = sessionInfo.expirationDate;
-    this.on(EVENTS.SESSION_EXTENDED, (expiresIn: number) => {
+    this.events.on(EVENTS.SESSION_EXTENDED, (expiresIn: number) => {
       this.info.expirationDate = Date.now() + expiresIn * 1000;
     });
   }