@inrupt/solid-client-authn-browser 1.17.1 → 1.17.3

package/src/Session.spec.ts

@@ -40,7 +40,7 @@ import type ClientAuthentication from "./ClientAuthentication";
 
 jest.mock("@inrupt/universal-fetch", () => {
   const fetchModule = jest.requireActual(
-    "@inrupt/universal-fetch"
+    "@inrupt/universal-fetch",
   ) as typeof UniversalFetch;
   return {
     ...fetchModule,
@@ -164,7 +164,7 @@ describe("Session", () => {
         expect.objectContaining({
           tokenType: "Bearer",
         }),
-        mySession
+        mySession,
       );
     });
 
@@ -246,26 +246,24 @@ describe("Session", () => {
     it("uses current window location as default redirect URL", async () => {
       mockLocation("https://some.url");
       const clientAuthentication = mockClientAuthentication();
-      const incomingRedirectHandler = jest.spyOn(
-        clientAuthentication,
-        "handleIncomingRedirect"
-      );
+      const incomingRedirectHandler = jest
+        .spyOn(clientAuthentication, "handleIncomingRedirect")
+        .mockResolvedValue(undefined);
 
       const mySession = new Session({ clientAuthentication });
       await mySession.handleIncomingRedirect();
       expect(incomingRedirectHandler).toHaveBeenCalledWith(
         "https://some.url",
-        mySession
+        mySession,
       );
     });
 
-    it("wraps up ClientAuthentication handleIncomingRedirect", async () => {
+    it("wraps ClientAuthentication handleIncomingRedirect", async () => {
       mockLocation("https://some.url");
       const clientAuthentication = mockClientAuthentication();
-      const incomingRedirectHandler = jest.spyOn(
-        clientAuthentication,
-        "handleIncomingRedirect"
-      );
+      const incomingRedirectHandler = jest
+        .spyOn(clientAuthentication, "handleIncomingRedirect")
+        .mockResolvedValue(undefined);
       const mySession = new Session({ clientAuthentication });
       await mySession.handleIncomingRedirect("https://some.url");
       expect(incomingRedirectHandler).toHaveBeenCalled();
@@ -299,12 +297,12 @@ describe("Session", () => {
             sessionId: "a session ID",
             webId: "https://some.webid#them",
           };
-        }
+        },
       );
       const mySession = new Session({ clientAuthentication });
       await mySession.handleIncomingRedirect("https://some.url");
       expect(window.localStorage.getItem(KEY_CURRENT_SESSION)).toBe(
-        mySession.info.sessionId
+        mySession.info.sessionId,
       );
     });
 
@@ -317,7 +315,7 @@ describe("Session", () => {
             sessionId: "a session ID",
             webId: "https://some.webid#them",
           };
-        }
+        },
       );
       const mySession = new Session({ clientAuthentication });
       await mySession.handleIncomingRedirect("https://some.url");
@@ -325,7 +323,7 @@ describe("Session", () => {
       await mySession.handleIncomingRedirect("https://some.url");
       // The second request should not hit the wrapped function
       expect(clientAuthentication.handleIncomingRedirect).toHaveBeenCalledTimes(
-        1
+        1,
       );
     });
 
@@ -336,7 +334,7 @@ describe("Session", () => {
       const clientAuthentication = mockClientAuthentication();
       const incomingRedirectHandler = jest.spyOn(
         clientAuthentication,
-        "handleIncomingRedirect"
+        "handleIncomingRedirect",
       );
       incomingRedirectHandler.mockResolvedValueOnce({
         isLoggedIn: true,
@@ -348,14 +346,14 @@ describe("Session", () => {
       expect(mySession.info.expirationDate).toBe(MOCK_TIMESTAMP + 1337);
       mySession.emit(EVENTS.SESSION_EXTENDED, 1337 * 2);
       expect(mySession.info.expirationDate).toBe(
-        MOCK_TIMESTAMP + 1337 * 2 * 1000
+        MOCK_TIMESTAMP + 1337 * 2 * 1000,
       );
     });
 
     it("leaves the session's info unchanged if no session is obtained after redirect", async () => {
       const clientAuthentication = mockClientAuthentication();
       clientAuthentication.handleIncomingRedirect = jest.fn(
-        async (_url: string) => undefined
+        async (_url: string) => undefined,
       );
       const mySession = new Session({ clientAuthentication }, "mySession");
       await mySession.handleIncomingRedirect("https://some.url");
@@ -382,10 +380,10 @@ describe("Session", () => {
       clientAuthentication.handleIncomingRedirect = jest.fn(blockingRequest);
       const mySession = new Session({ clientAuthentication });
       const firstTokenRequest = mySession.handleIncomingRedirect(
-        "https://my.app/?code=someCode&state=arizona"
+        "https://my.app/?code=someCode&state=arizona",
       );
       const secondTokenRequest = mySession.handleIncomingRedirect(
-        "https://my.app/?code=someCode&state=arizona"
+        "https://my.app/?code=someCode&state=arizona",
       );
       // We know that it has been set by the call to `blockingRequest`.
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -401,16 +399,15 @@ describe("Session", () => {
 
     it("preserves a binding to its Session instance", async () => {
       const clientAuthentication = mockClientAuthentication();
-      const incomingRedirectHandler = jest.spyOn(
-        clientAuthentication,
-        "handleIncomingRedirect"
-      );
+      const incomingRedirectHandler = jest
+        .spyOn(clientAuthentication, "handleIncomingRedirect")
+        .mockResolvedValue(undefined);
       const mySession = new Session({ clientAuthentication });
       const objectWithHandleIncomingRedirect = {
         handleIncomingRedirect: mySession.handleIncomingRedirect,
       };
       await objectWithHandleIncomingRedirect.handleIncomingRedirect(
-        "https://some.url"
+        "https://some.url",
       );
       expect(incomingRedirectHandler).toHaveBeenCalled();
     });
@@ -422,7 +419,7 @@ describe("Session", () => {
       mockLocation("https://mock.current/location");
       const mockedStorage = new StorageUtility(
         mockStorage({}),
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -431,7 +428,7 @@ describe("Session", () => {
       clientAuthentication.handleIncomingRedirect = jest
         .fn()
         .mockReturnValue(
-          incomingRedirectPromise
+          incomingRedirectPromise,
         ) as typeof clientAuthentication.handleIncomingRedirect;
       const mySession = new Session({ clientAuthentication });
       // eslint-disable-next-line no-void
@@ -456,7 +453,7 @@ describe("Session", () => {
         }),
         // No session information need to be mocked, because `validateCurrentSession`
         // itself is mocked.
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -465,15 +462,15 @@ describe("Session", () => {
       clientAuthentication.handleIncomingRedirect = jest
         .fn()
         .mockReturnValueOnce(
-          incomingRedirectPromise
+          incomingRedirectPromise,
         ) as typeof clientAuthentication.handleIncomingRedirect;
       const validateCurrentSessionPromise = Promise.resolve(
-        "https://some.issuer/"
+        "https://some.issuer/",
       );
       clientAuthentication.validateCurrentSession = jest
         .fn()
         .mockReturnValue(
-          validateCurrentSessionPromise
+          validateCurrentSessionPromise,
         ) as typeof clientAuthentication.validateCurrentSession;
 
       const mySession = new Session({ clientAuthentication });
@@ -485,7 +482,7 @@ describe("Session", () => {
       await incomingRedirectPromise;
       await validateCurrentSessionPromise;
       expect(window.localStorage.getItem(KEY_CURRENT_URL)).toBe(
-        "https://mock.current/location"
+        "https://mock.current/location",
       );
     });
 
@@ -505,7 +502,7 @@ describe("Session", () => {
           [`${USER_SESSION_PREFIX}:${sessionId}`]: {
             clientId: "value doesn't matter",
           },
-        })
+        }),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -513,7 +510,7 @@ describe("Session", () => {
       clientAuthentication.handleIncomingRedirect = (
         jest.fn() as any
       ).mockResolvedValue(
-        undefined
+        undefined,
       ) as typeof clientAuthentication.handleIncomingRedirect;
       const mySession = new Session({ clientAuthentication });
       // eslint-disable-next-line no-void
@@ -536,7 +533,7 @@ describe("Session", () => {
             isLoggedIn: "true",
           },
         }),
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -551,13 +548,13 @@ describe("Session", () => {
       clientAuthentication.validateCurrentSession = jest
         .fn()
         .mockReturnValue(
-          validateCurrentSessionPromise
+          validateCurrentSessionPromise,
         ) as typeof clientAuthentication.validateCurrentSession;
       const incomingRedirectPromise = Promise.resolve();
       clientAuthentication.handleIncomingRedirect = jest
         .fn()
         .mockReturnValueOnce(
-          incomingRedirectPromise
+          incomingRedirectPromise,
         ) as typeof clientAuthentication.handleIncomingRedirect;
       clientAuthentication.login = jest.fn<typeof clientAuthentication.login>();
 
@@ -579,11 +576,11 @@ describe("Session", () => {
           clientSecret: "some client secret",
           redirectUrl: "https://some.redirect/url",
         },
-        expect.anything()
+        expect.anything(),
       );
       // Check that second parameter is of type session
       expect(
-        (clientAuthentication.login as any).mock.calls[0][1]
+        (clientAuthentication.login as any).mock.calls[0][1],
       ).toBeInstanceOf(Session);
     });
 
@@ -599,7 +596,7 @@ describe("Session", () => {
             isLoggedIn: "true",
           },
         }),
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -608,13 +605,13 @@ describe("Session", () => {
       clientAuthentication.validateCurrentSession = jest
         .fn()
         .mockReturnValue(
-          validateCurrentSessionPromise
+          validateCurrentSessionPromise,
         ) as typeof clientAuthentication.validateCurrentSession;
       const incomingRedirectPromise = Promise.resolve();
       clientAuthentication.handleIncomingRedirect = jest
         .fn()
         .mockReturnValueOnce(
-          incomingRedirectPromise
+          incomingRedirectPromise,
         ) as typeof clientAuthentication.handleIncomingRedirect;
       clientAuthentication.login = jest.fn<typeof clientAuthentication.login>();
 
@@ -640,7 +637,7 @@ describe("Session", () => {
             isLoggedIn: "true",
           },
         }),
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -656,7 +653,7 @@ describe("Session", () => {
       clientAuthentication.handleIncomingRedirect = (
         jest.fn() as any
       ).mockResolvedValue(
-        undefined
+        undefined,
       ) as typeof clientAuthentication.handleIncomingRedirect;
       clientAuthentication.login = jest.fn<typeof clientAuthentication.login>();
 
@@ -679,7 +676,7 @@ describe("Session", () => {
             isLoggedIn: "true",
           },
         }),
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -720,7 +717,7 @@ describe("Session", () => {
             isLoggedIn: "true",
           },
         }),
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -759,7 +756,7 @@ describe("Session", () => {
             isLoggedIn: "true",
           },
         }),
-        mockStorage({})
+        mockStorage({}),
       );
       const clientAuthentication = mockClientAuthentication({
         sessionInfoManager: mockSessionInfoManager(mockedStorage),
@@ -781,7 +778,7 @@ describe("Session", () => {
         mySession.emit(EVENTS.ERROR, "error", "error_description");
         expect(onErrorCallback).toHaveBeenCalledWith(
           "error",
-          "error_description"
+          "error_description",
         );
       });
     });
@@ -807,7 +804,7 @@ describe("Session", () => {
       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!"
+            "Should *NOT* call callback - this means test has failed!",
           );
         };
         const clientAuthentication = mockClientAuthentication();
@@ -818,12 +815,12 @@ describe("Session", () => {
               sessionId: "a session ID",
               webId: "https://some.webid#them",
             };
-          }
+          },
         );
         const mySession = new Session({ clientAuthentication });
         mySession.onLogin(failCallback);
         await expect(
-          mySession.handleIncomingRedirect("https://some.url")
+          mySession.handleIncomingRedirect("https://some.url"),
         ).resolves.not.toThrow();
       });
 
@@ -836,7 +833,7 @@ describe("Session", () => {
               sessionId: "a session ID",
               webId: "https://some.webid#them",
             };
-          }
+          },
         );
         const mySession = new Session({ clientAuthentication });
         const myCallback = jest.fn((): void => {
@@ -1035,7 +1032,7 @@ describe("Session", () => {
       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"
+        "[onLogin] is not supported",
       );
     });
   });

package/src/Session.ts

@@ -101,7 +101,7 @@ export interface IHandleIncomingRedirectOptions {
 export async function silentlyAuthenticate(
   sessionId: string,
   clientAuthn: ClientAuthentication,
-  session: Session
+  session: Session,
 ): Promise<boolean> {
   const storedSessionInfo = await clientAuthn.validateCurrentSession(sessionId);
   if (storedSessionInfo !== null) {
@@ -120,7 +120,7 @@ export async function silentlyAuthenticate(
         clientSecret: storedSessionInfo.clientAppSecret,
         tokenType: storedSessionInfo.tokenType ?? "DPoP",
       },
-      session.events
+      session.events,
     );
     return true;
   }
@@ -128,7 +128,7 @@ export async function silentlyAuthenticate(
 }
 
 function isLoggedIn(
-  sessionInfo?: ISessionInfo
+  sessionInfo?: ISessionInfo,
 ): sessionInfo is ISessionInfo & { isLoggedIn: true } {
   return !!sessionInfo?.isLoggedIn;
 }
@@ -170,7 +170,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
    */
   constructor(
     sessionOptions: Partial<ISessionOptions> = {},
-    sessionId: string | undefined = undefined
+    sessionId: string | undefined = undefined,
   ) {
     super();
     // Until Session no longer implements EventEmitter, this.events is just a proxy
@@ -181,8 +181,8 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
       this,
       buildProxyHandler(
         Session.prototype,
-        "events only implements ISessionEventListener"
-      )
+        "events only implements ISessionEventListener",
+      ),
     );
     if (sessionOptions.clientAuthentication) {
       this.clientAuthentication = sessionOptions.clientAuthentication;
@@ -213,7 +213,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
     // (as opposed to using our storage abstraction layer) because it is only
     // used in a browser-specific mechanism.
     this.events.on(EVENTS.LOGIN, () =>
-      window.localStorage.setItem(KEY_CURRENT_SESSION, this.info.sessionId)
+      window.localStorage.setItem(KEY_CURRENT_SESSION, this.info.sessionId),
     );
 
     this.events.on(EVENTS.SESSION_EXPIRED, () => this.internalLogout(false));
@@ -237,7 +237,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
         // Defaults the token type to DPoP
         tokenType: options.tokenType ?? "DPoP",
       },
-      this.events
+      this.events,
     );
     // `login` redirects the user away from the app,
     // so unless it throws an error, there is no code that should run afterwards
@@ -264,7 +264,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
    */
   private internalLogout = async (
     emitSignal: boolean,
-    options?: ILogoutOptions
+    options?: ILogoutOptions,
   ): Promise<void> => {
     // Clearing this value means that silent refresh will no longer be attempted.
     // In particular, in the case of a silent authentication error it prevents
@@ -293,14 +293,20 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
    * ```
    *
    * IDP logout will log the user out of their Solid identity provider,
-   * and will redirect the user away from the application to do so.
+   * and will redirect the user away from the application to do so. In order
+   * for users to be redirected back to `postLogoutUrl` you MUST include the
+   * `postLogoutUrl` value in the `post_logout_redirect_uris` field in the
+   * [Client ID Document](https://docs.inrupt.com/ess/latest/security/authentication/#client-identifier-client-id).
    * IDP logout can be performed as follows:
    * ```typescript
    * await session.logout({
    *  logoutType: 'idp',
    *  // An optional URL to redirect to after logout has completed;
-   *  // this MUST match a logout URL listed in the clientId of
-   *  // the application that is logged in.
+   *  // this MUST match a logout URL listed in the Client ID Document
+   *  // of the application that is logged in.
+   *  // If the application is logged in with a Client ID that is not
+   *  // a URI dereferencing to a Client ID Document then users will
+   *  // not be redirected back to the `postLogoutUrl` after logout.
    *  postLogoutUrl: 'https://example.com/logout',
    *  // An optional value to be included in the query parameters
    *  // when the IDP provider redirects the user to the postLogoutRedirectUrl.
@@ -318,7 +324,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
    * @param options See {@see IHandleIncomingRedirectOptions}.
    */
   handleIncomingRedirect = async (
-    inputOptions: string | IHandleIncomingRedirectOptions = {}
+    inputOptions: string | IHandleIncomingRedirectOptions = {},
   ): Promise<ISessionInfo | undefined> => {
     if (this.info.isLoggedIn) {
       return this.info;
@@ -334,7 +340,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
     this.tokenRequestInProgress = true;
     const sessionInfo = await this.clientAuthentication.handleIncomingRedirect(
       url,
-      this.events
+      this.events,
     );
     if (isLoggedIn(sessionInfo)) {
       this.setSessionInfo(sessionInfo);
@@ -363,7 +369,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
         const attemptedSilentAuthentication = await silentlyAuthenticate(
           storedSessionId,
           this.clientAuthentication,
-          this
+          this,
         );
         // At this point, we know that the main window will imminently be redirected.
         // However, this redirect is asynchronous and there is no way to halt execution
@@ -410,8 +416,8 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
   onError(
     callback: (
       error: string | null,
-      errorDescription?: string | null
-    ) => unknown
+      errorDescription?: string | null,
+    ) => unknown,
   ): void {
     this.events.on(EVENTS.ERROR, callback);
   }
@@ -441,7 +447,7 @@ export class Session extends EventEmitter implements IHasSessionEventListener {
   }
 
   private setSessionInfo(
-    sessionInfo: ISessionInfo & { isLoggedIn: true }
+    sessionInfo: ISessionInfo & { isLoggedIn: true },
   ): void {
     this.info.isLoggedIn = sessionInfo.isLoggedIn;
     this.info.webId = sessionInfo.webId;

package/src/__mocks__/ClientAuthentication.ts

@@ -48,7 +48,7 @@ type ClientAuthnDependencies = {
 };
 
 export const mockClientAuthentication = (
-  mocks?: Partial<ClientAuthnDependencies>
+  mocks?: Partial<ClientAuthnDependencies>,
 ): ClientAuthentication => {
   const storage = mocks?.storage ?? mockStorageUtility({});
   return new ClientAuthentication(
@@ -56,6 +56,6 @@ export const mockClientAuthentication = (
     mocks?.redirectHandler ?? mockIncomingRedirectHandler(),
     mocks?.logoutHandler ?? mockLogoutHandler(storage),
     mocks?.sessionInfoManager ?? mockSessionInfoManager(storage),
-    mocks?.issuerConfigFetcher ?? IssuerConfigFetcherMock
+    mocks?.issuerConfigFetcher ?? IssuerConfigFetcherMock,
   );
 };

package/src/defaultSession.ts

@@ -70,7 +70,8 @@ export const login: Session["login"] = (...args) => {
  * Logs the user out of the application.
  *
  * By default this does not log the user out of their Solid identity provider.
- * In order to do so, you must set the logoutType to `idp`.
+ * In order to do so, you must set the logoutType to `idp`. For usage details
+ * see {@link Session.logout}.
  *
  * @since 1.3.0
  */
@@ -113,7 +114,7 @@ export const onLogin: Session["onLogin"] = (...args) => {
  * @param callback The function called when a user completes logout.
  * @since 1.3.0
  * @deprecated Prefer events.on(EVENTS.LOGOUT, callback)
-
+ *
  */
 export const onLogout: Session["onLogout"] = (...args) => {
   const session = getDefaultSession();
@@ -135,7 +136,7 @@ export const onSessionRestore: Session["onSessionRestore"] = (...args) => {
 /**
  * {@link SessionEventEmitter} instance to subscribe to events by the default session.
  *
- * @since Unreleased
+ * @since 1.14.0
  */
 export const events = (): Session["events"] => {
   return getDefaultSession().events;

package/src/dependencies.ts

@@ -62,7 +62,7 @@ export function getClientAuthenticationWithDependencies(dependencies: {
 
   const storageUtility = new StorageUtilityBrowser(
     secureStorage,
-    insecureStorage
+    insecureStorage,
   );
 
   const issuerConfigFetcher = new IssuerConfigFetcher(storageUtility);
@@ -73,7 +73,7 @@ export function getClientAuthenticationWithDependencies(dependencies: {
   const tokenRefresher = new TokenRefresher(
     storageUtility,
     issuerConfigFetcher,
-    clientRegistrar
+    clientRegistrar,
   );
 
   const redirector = new Redirector();
@@ -83,7 +83,7 @@ export function getClientAuthenticationWithDependencies(dependencies: {
     storageUtility,
     new AuthorizationCodeWithPkceOidcHandler(storageUtility, redirector),
     issuerConfigFetcher,
-    clientRegistrar
+    clientRegistrar,
   );
 
   const redirectHandler = new AggregateRedirectHandler([
@@ -93,7 +93,7 @@ export function getClientAuthenticationWithDependencies(dependencies: {
       sessionInfoManager,
       issuerConfigFetcher,
       clientRegistrar,
-      tokenRefresher
+      tokenRefresher,
     ),
     // This catch-all class will always be able to handle the
     // redirect IRI, so it must be registered last.
@@ -105,6 +105,6 @@ export function getClientAuthenticationWithDependencies(dependencies: {
     redirectHandler,
     new IWaterfallLogoutHandler(sessionInfoManager, redirector),
     sessionInfoManager,
-    issuerConfigFetcher
+    issuerConfigFetcher,
   );
 }