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

package/dist/index.js

@@ -6,18 +6,82 @@ var EventEmitter = require('events');
 var oidcClientExt = require('@inrupt/oidc-client-ext');
 var universalFetch = require('@inrupt/universal-fetch');
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * This class in a no-value-added extension of StorageUtility from the core module.
+ * The reason it has to be declared is for TSyringe to find the decorators in the
+ * same modules as where the dependency container is declared (in this case,
+ * the browser module, with the dependancy container in dependencies.ts).
+ * @hidden
+ */
 class StorageUtilityBrowser extends solidClientAuthnCore.StorageUtility {
     constructor(secureStorage, insecureStorage) {
         super(secureStorage, insecureStorage);
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @hidden
+ */
 class ClientAuthentication extends solidClientAuthnCore.ClientAuthentication {
     constructor() {
         super(...arguments);
+        // Define these functions as properties so that they don't get accidentally re-bound.
+        // Isn't Javascript fun?
         this.login = async (options, eventEmitter) => {
             var _a, _b;
+            // In order to get a clean start, make sure that the session is logged out
+            // on login.
+            // But we may want to preserve our client application info, particularly if
+            // we used Dynamic Client Registration to register (since we don't
+            // necessarily want the user to have to register this app each time they
+            // login).
             await this.sessionInfoManager.clear(options.sessionId);
+            // In the case of the user hitting the 'back' button in their browser, they
+            // could return to a previous redirect URL that contains OIDC params that
+            // are now longer valid. To be safe, strip relevant params now.
+            // If the user is providing a redirect IRI, it should not be modified, so
+            // normalization only applies if we default to the current location (which is
+            // a bad practice and should be discouraged).
             const redirectUrl = (_a = options.redirectUrl) !== null && _a !== void 0 ? _a : oidcClientExt.removeOidcQueryParam(window.location.href);
             if (!solidClientAuthnCore.isValidRedirectUrl(redirectUrl)) {
                 throw new Error(`${redirectUrl} is not a valid redirect URL, it is either a malformed IRI, includes a hash fragment, or reserved query parameters ('code' or 'state').`);
@@ -25,10 +89,15 @@ class ClientAuthentication extends solidClientAuthnCore.ClientAuthentication {
             await this.loginHandler.handle({
                 ...options,
                 redirectUrl,
+                // If no clientName is provided, the clientId may be used instead.
                 clientName: (_b = options.clientName) !== null && _b !== void 0 ? _b : options.clientId,
                 eventEmitter,
             });
         };
+        // Collects session information from storage, and returns them. Returns null
+        // if the expected information cannot be found.
+        // Note that the ID token is not stored, which means the session information
+        // cannot be validated at this point.
         this.validateCurrentSession = async (currentSessionId) => {
             const sessionInfo = await this.sessionInfoManager.get(currentSessionId);
             if (sessionInfo === undefined ||
@@ -41,9 +110,14 @@ class ClientAuthentication extends solidClientAuthnCore.ClientAuthentication {
         this.handleIncomingRedirect = async (url, eventEmitter) => {
             try {
                 const redirectInfo = await this.redirectHandler.handle(url, eventEmitter);
+                // The `FallbackRedirectHandler` directly returns the global `fetch` for
+                // his value, so we should ensure it's bound to `window` rather than to
+                // ClientAuthentication, to avoid the following error:
+                // > 'fetch' called on an object that does not implement interface Window.
                 this.fetch = redirectInfo.fetch.bind(window);
                 this.boundLogout = redirectInfo.getLogoutUrl;
-                this.cleanUrlAfterRedirect(url);
+                // Strip the oauth params:
+                await this.cleanUrlAfterRedirect(url);
                 return {
                     isLoggedIn: redirectInfo.isLoggedIn,
                     webId: redirectInfo.webId,
@@ -52,31 +126,79 @@ class ClientAuthentication extends solidClientAuthnCore.ClientAuthentication {
                 };
             }
             catch (err) {
-                this.cleanUrlAfterRedirect(url);
+                // Strip the oauth params:
+                await this.cleanUrlAfterRedirect(url);
+                // FIXME: EVENTS.ERROR should be errorCode, errorDescription
+                //
+                // I'm not sure if "redirect" is a good error code, and in theory `err`
+                // maybe an Error object and not a string; Maybe we want to just hardcode
+                // a description instead?
                 eventEmitter.emit(solidClientAuthnCore.EVENTS.ERROR, "redirect", err);
                 return undefined;
             }
         };
     }
-    cleanUrlAfterRedirect(url) {
+    async cleanUrlAfterRedirect(url) {
         const cleanedUpUrl = new URL(url);
         cleanedUpUrl.searchParams.delete("state");
+        // For auth code flow
         cleanedUpUrl.searchParams.delete("code");
+        // For implicit flow
         cleanedUpUrl.searchParams.delete("id_token");
         cleanedUpUrl.searchParams.delete("access_token");
+        // For login error
         cleanedUpUrl.searchParams.delete("error");
         cleanedUpUrl.searchParams.delete("error_description");
         cleanedUpUrl.searchParams.delete("iss");
+        // Remove OAuth-specific query params (since the login flow finishes with
+        // the browser being redirected back with OAuth2 query params (e.g. for
+        // 'code' and 'state'), and so if the user simply refreshes this page our
+        // authentication library will be called again with what are now invalid
+        // query parameters!).
         window.history.replaceState(null, "", cleanedUpUrl.toString());
+        while (window.location.href !== cleanedUpUrl.href) {
+            // Poll the current URL every ms. Active polling is required because
+            // window.history.replaceState is asynchronous, but the associated
+            // 'popstate' event which should be listened to is only sent on active
+            // navigation, which we will not have here.
+            // See https://developer.mozilla.org/en-US/docs/Web/API/Window/popstate_event#when_popstate_is_sent
+            // eslint-disable-next-line no-await-in-loop
+            await new Promise((resolve) => {
+                setTimeout(() => resolve(), 1);
+            });
+        }
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
 function hasIssuer(options) {
     return typeof options.oidcIssuer === "string";
 }
 function hasRedirectUrl(options) {
     return typeof options.redirectUrl === "string";
 }
+/**
+ * @hidden
+ */
 class OidcLoginHandler {
     constructor(storageUtility, oidcHandler, issuerConfigFetcher, clientRegistrar) {
         this.storageUtility = storageUtility;
@@ -98,22 +220,57 @@ class OidcLoginHandler {
         if (!hasRedirectUrl(options)) {
             throw new solidClientAuthnCore.ConfigurationError(`OidcLoginHandler requires a redirect URL: missing property 'redirectUrl' in ${JSON.stringify(options)}`);
         }
+        // Fetch issuer config.
         const issuerConfig = await this.issuerConfigFetcher.fetchConfig(options.oidcIssuer);
         const clientRegistration = await solidClientAuthnCore.handleRegistration(options, issuerConfig, this.storageUtility, this.clientRegistrar);
+        // Construct OIDC Options
         const OidcOptions = {
+            // Note that here, the issuer is not the one from the received options, but
+            // from the issuer's config. This enforces the canonical URL is used and stored,
+            // which is also the one present in the ID token, so storing a technically
+            // valid, but different issuer URL (e.g. using a trailing slash or not) now
+            // could prevent from validating the ID token later.
             issuer: issuerConfig.issuer,
+            // TODO: differentiate if DPoP should be true
             dpop: options.tokenType.toLowerCase() === "dpop",
             ...options,
             issuerConfiguration: issuerConfig,
             client: clientRegistration,
         };
+        // Call proper OIDC Handler
         return this.oidcHandler.handle(OidcOptions);
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @hidden
+ * Authorization code flow spec: https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
+ * PKCE: https://tools.ietf.org/html/rfc7636
+ */
 class AuthorizationCodeWithPkceOidcHandler extends solidClientAuthnCore.AuthorizationCodeWithPkceOidcHandlerBase {
     async handle(oidcLoginOptions) {
         var _a;
+        /* eslint-disable camelcase */
         const oidcOptions = {
             authority: oidcLoginOptions.issuer.toString(),
             client_id: oidcLoginOptions.client.clientId,
@@ -123,28 +280,58 @@ class AuthorizationCodeWithPkceOidcHandler extends solidClientAuthnCore.Authoriz
             response_type: "code",
             scope: solidClientAuthnCore.DEFAULT_SCOPES,
             filterProtocolClaims: true,
+            // The userinfo endpoint on NSS fails, so disable this for now
+            // Note that in Solid, information should be retrieved from the
+            // profile referenced by the WebId.
             loadUserInfo: false,
             code_verifier: true,
             prompt: (_a = oidcLoginOptions.prompt) !== null && _a !== void 0 ? _a : "consent",
         };
+        /* eslint-enable camelcase */
         const oidcClientLibrary = new oidcClientExt.OidcClient(oidcOptions);
         try {
             const signingRequest = await oidcClientLibrary.createSigninRequest();
+            // Make sure to await the promise before returning so that the error is caught.
             return await this.handleRedirect({
                 oidcLoginOptions,
+                // eslint-disable-next-line no-underscore-dangle
                 state: signingRequest.state._id,
+                // eslint-disable-next-line no-underscore-dangle
                 codeVerifier: signingRequest.state._code_verifier,
                 targetUrl: signingRequest.url.toString(),
             });
         }
         catch (err) {
+            // eslint-disable-next-line no-console
             console.error(err);
         }
+        // The login is only completed AFTER redirect, so nothing to return here.
         return undefined;
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
 const WELL_KNOWN_OPENID_CONFIG = ".well-known/openid-configuration";
+/* eslint-disable camelcase */
 const issuerConfigKeyMap = {
     issuer: {
         toKey: "issuer",
@@ -232,10 +419,15 @@ const issuerConfigKeyMap = {
         convertToUrl: true,
     },
 };
+/* eslint-enable camelcase */
 function processConfig(config) {
     const parsedConfig = {};
     Object.keys(config).forEach((key) => {
         if (issuerConfigKeyMap[key]) {
+            // TODO: PMcB55: Validate URL if "issuerConfigKeyMap[key].convertToUrl"
+            //  if (issuerConfigKeyMap[key].convertToUrl) {
+            //   validateUrl(config[key]);
+            //  }
             parsedConfig[issuerConfigKeyMap[key].toKey] = config[key];
         }
     });
@@ -244,33 +436,71 @@ function processConfig(config) {
     }
     return parsedConfig;
 }
+/**
+ * @hidden
+ */
 class IssuerConfigFetcher {
     constructor(storageUtility) {
         this.storageUtility = storageUtility;
         this.storageUtility = storageUtility;
     }
+    // This method needs no state (so can be static), and can be exposed to allow
+    // callers to know where this implementation puts state it needs.
     static getLocalStorageKey(issuer) {
         return `issuerConfig:${issuer}`;
     }
     async fetchConfig(issuer) {
         let issuerConfig;
-        const openIdConfigUrl = new URL(WELL_KNOWN_OPENID_CONFIG, issuer.endsWith("/") ? issuer : `${issuer}/`).href;
+        const openIdConfigUrl = new URL(WELL_KNOWN_OPENID_CONFIG, 
+        // Make sure to append a slash at issuer URL, so that the .well-known URL
+        // includes the full issuer path. See https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig.
+        issuer.endsWith("/") ? issuer : `${issuer}/`).href;
         const issuerConfigRequestBody = await universalFetch.fetch.call(globalThis, openIdConfigUrl);
+        // Check the validity of the fetched config
         try {
             issuerConfig = processConfig(await issuerConfigRequestBody.json());
         }
         catch (err) {
             throw new solidClientAuthnCore.ConfigurationError(`[${issuer.toString()}] has an invalid configuration: ${err.message}`);
         }
+        // Update store with fetched config
         await this.storageUtility.set(IssuerConfigFetcher.getLocalStorageKey(issuer), JSON.stringify(issuerConfig));
         return issuerConfig;
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @param sessionId
+ * @param storage
+ * @hidden
+ */
 async function clear(sessionId, storage) {
     await solidClientAuthnCore.clear(sessionId, storage);
     await oidcClientExt.clearOidcPersistentStorage();
 }
+/**
+ * @hidden
+ */
 class SessionInfoManager extends solidClientAuthnCore.SessionInfoManagerBase {
     async get(sessionId) {
         const [isLoggedIn, webId, clientId, clientSecret, redirectUrl, refreshToken, issuer, tokenType,] = await Promise.all([
@@ -300,6 +530,9 @@ class SessionInfoManager extends solidClientAuthnCore.SessionInfoManagerBase {
             }),
         ]);
         if (typeof redirectUrl === "string" && !solidClientAuthnCore.isValidRedirectUrl(redirectUrl)) {
+            // This resolves the issue for people experiencing https://github.com/inrupt/solid-client-authn-js/issues/2891.
+            // An invalid redirect URL is present in the storage, and the session should
+            // be cleared to get a fresh start. This will require the user to log back in.
             await Promise.all([
                 this.storageUtility.deleteAllUserData(sessionId, { secure: false }),
                 this.storageUtility.deleteAllUserData(sessionId, { secure: true }),
@@ -324,17 +557,52 @@ class SessionInfoManager extends solidClientAuthnCore.SessionInfoManagerBase {
             issuer,
             clientAppId: clientId,
             clientAppSecret: clientSecret,
+            // Default the token type to DPoP if unspecified.
             tokenType: tokenType !== null && tokenType !== void 0 ? tokenType : "DPoP",
         };
     }
+    /**
+     * This function removes all session-related information from storage.
+     * @param sessionId the session identifier
+     * @param storage the storage where session info is stored
+     * @hidden
+     */
     async clear(sessionId) {
         return clear(sessionId, this.storageUtility);
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * This class handles redirect IRIs without any query params, and returns an unauthenticated
+ * session. It serves as a fallback so that consuming libraries don't have to test
+ * for the query params themselves, and can always try to use them as a redirect IRI.
+ * @hidden
+ */
 class FallbackRedirectHandler {
     async canHandle(redirectUrl) {
         try {
+            // The next URL object is built for validating it.
+            // eslint-disable-next-line no-new
             new URL(redirectUrl);
             return true;
         }
@@ -342,12 +610,44 @@ class FallbackRedirectHandler {
             throw new Error(`[${redirectUrl}] is not a valid URL, and cannot be used as a redirect URL: ${e}`);
         }
     }
-    async handle(_redirectUrl) {
+    async handle(
+    // The argument is ignored, but must be present to implement the interface
+    _redirectUrl) {
         return solidClientAuthnCore.getUnauthenticatedSession();
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @hidden
+ * @packageDocumentation
+ */
+// FIXME: The following doesn't work in the browser, it results in all the fetches
+// being unauthenticated. This should be looked into when migrating to universal-fetch.
+// import { fetch } from "cross-fetch";
 const globalFetch = (...args) => universalFetch.fetch.call(globalThis, ...args);
+/**
+ * @hidden
+ */
 class AuthCodeRedirectHandler {
     constructor(storageUtility, sessionInfoManager, issuerConfigFetcher, clientRegistrar, tokerRefresher) {
         this.storageUtility = storageUtility;
@@ -397,10 +697,15 @@ class AuthCodeRedirectHandler {
         if (isDpop) {
             tokens = await oidcClientExt.getDpopToken(issuerConfig, client, {
                 grantType: "authorization_code",
+                // We rely on our 'canHandle' function checking that the OAuth 'code'
+                // parameter is present in our query string.
                 code: url.searchParams.get("code"),
                 codeVerifier,
                 redirectUrl: storedRedirectIri,
             });
+            // Delete oidc-client-specific session information from storage. This is
+            // done automatically when retrieving a bearer token, but since the DPoP
+            // binding uses our custom code, this needs to be done manually.
             window.localStorage.removeItem(`oidc.${oauthState}`);
         }
         else {
@@ -441,12 +746,58 @@ class AuthCodeRedirectHandler {
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @hidden
+ */
 class AggregateRedirectHandler extends solidClientAuthnCore.AggregateHandler {
     constructor(redirectHandlers) {
         super(redirectHandlers);
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @hidden
+ */
 class BrowserStorage {
     get storage() {
         return window.localStorage;
@@ -462,6 +813,29 @@ class BrowserStorage {
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @hidden
+ */
 class Redirector {
     redirect(redirectUrl, options) {
         if (options && options.handleRedirect) {
@@ -476,19 +850,49 @@ class Redirector {
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * @hidden
+ */
 class ClientRegistrar {
     constructor(storageUtility) {
         this.storageUtility = storageUtility;
         this.storageUtility = storageUtility;
     }
     async getClient(options, issuerConfig) {
-        const [storedClientId, storedClientSecret,] = await Promise.all([
+        // If client secret and/or client id are stored in storage, use those.
+        const [storedClientId, storedClientSecret,
+        // storedClientName,
+        ] = await Promise.all([
             this.storageUtility.getForUser(options.sessionId, "clientId", {
                 secure: false,
             }),
             this.storageUtility.getForUser(options.sessionId, "clientSecret", {
                 secure: false,
             }),
+            // this.storageUtility.getForUser(options.sessionId, "clientName", {
+            //   // FIXME: figure out how to persist secure storage at reload
+            //   secure: false,
+            // }),
         ]);
         if (storedClientId) {
             return {
@@ -499,6 +903,7 @@ class ClientRegistrar {
         }
         try {
             const registeredClient = await oidcClientExt.registerClient(options, issuerConfig);
+            // Save info
             const infoToSave = {
                 clientId: registeredClient.clientId,
             };
@@ -510,6 +915,9 @@ class ClientRegistrar {
                     registeredClient.idTokenSignedResponseAlg;
             }
             await this.storageUtility.setForUser(options.sessionId, infoToSave, {
+                // FIXME: figure out how to persist secure storage at reload
+                // Otherwise, the client info cannot be retrieved from storage, and
+                // the lib tries to re-register the client on each fetch
                 secure: false,
             });
             return registeredClient;
@@ -520,9 +928,36 @@ class ClientRegistrar {
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ * This class handles redirect IRIs without any query params, and returns an unauthenticated
+ * session. It serves as a fallback so that consuming libraries don't have to test
+ * for the query params themselves, and can always try to use them as a redirect IRI.
+ * @hidden
+ */
 class ErrorOidcHandler {
     async canHandle(redirectUrl) {
         try {
+            // eslint-disable-next-line no-new
             return new URL(redirectUrl).searchParams.has("error");
         }
         catch (e) {
@@ -540,6 +975,32 @@ class ErrorOidcHandler {
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+// Some identifiers are not in camelcase on purpose, as they are named using the
+// official names from the OIDC/OAuth2 specifications.
+/* eslint-disable camelcase */
+/**
+ * @hidden
+ */
 class TokenRefresher {
     constructor(storageUtility, issuerConfigFetcher, clientRegistrar) {
         this.storageUtility = storageUtility;
@@ -551,8 +1012,10 @@ class TokenRefresher {
     }
     async refresh(sessionId, refreshToken, dpopKey, eventEmitter) {
         const oidcContext = await solidClientAuthnCore.loadOidcContextFromStorage(sessionId, this.storageUtility, this.issuerConfigFetcher);
+        // This should also retrieve the client from storage
         const clientInfo = await this.clientRegistrar.getClient({ sessionId }, oidcContext.issuerConfig);
         if (refreshToken === undefined) {
+            // TODO: in a next PR, look up storage for a refresh token
             throw new Error(`Session [${sessionId}] has no refresh token to allow it to refresh its access token.`);
         }
         if (oidcContext.dpop && dpopKey === undefined) {
@@ -569,6 +1032,31 @@ class TokenRefresher {
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+/**
+ *
+ * @param dependencies
+ * @deprecated This function will be removed from the external API in an upcoming release.
+ */
 function getClientAuthenticationWithDependencies(dependencies) {
     const inMemoryStorage = new solidClientAuthnCore.InMemoryStorage();
     const secureStorage = dependencies.secureStorage || inMemoryStorage;
@@ -579,22 +1067,69 @@ function getClientAuthenticationWithDependencies(dependencies) {
     const sessionInfoManager = new SessionInfoManager(storageUtility);
     const tokenRefresher = new TokenRefresher(storageUtility, issuerConfigFetcher, clientRegistrar);
     const redirector = new Redirector();
+    // make new handler for redirect and login
     const loginHandler = new OidcLoginHandler(storageUtility, new AuthorizationCodeWithPkceOidcHandler(storageUtility, redirector), issuerConfigFetcher, clientRegistrar);
     const redirectHandler = new AggregateRedirectHandler([
         new ErrorOidcHandler(),
         new AuthCodeRedirectHandler(storageUtility, sessionInfoManager, issuerConfigFetcher, clientRegistrar, tokenRefresher),
+        // This catch-all class will always be able to handle the
+        // redirect IRI, so it must be registered last.
         new FallbackRedirectHandler(),
     ]);
     return new ClientAuthentication(loginHandler, redirectHandler, new solidClientAuthnCore.IWaterfallLogoutHandler(sessionInfoManager, redirector), sessionInfoManager, issuerConfigFetcher);
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
 const KEY_CURRENT_SESSION = `${solidClientAuthnCore.SOLID_CLIENT_AUTHN_KEY_PREFIX}currentSession`;
 const KEY_CURRENT_URL = `${solidClientAuthnCore.SOLID_CLIENT_AUTHN_KEY_PREFIX}currentUrl`;
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
 async function silentlyAuthenticate(sessionId, clientAuthn, session) {
     var _a;
     const storedSessionInfo = await clientAuthn.validateCurrentSession(sessionId);
     if (storedSessionInfo !== null) {
+        // It can be really useful to save the user's current browser location,
+        // so that we can restore it after completing the silent authentication
+        // on incoming redirect. This way, the user is eventually redirected back
+        // to the page they were on and not to the app's redirect page.
         window.localStorage.setItem(KEY_CURRENT_URL, window.location.href);
         await clientAuthn.login({
             sessionId,
@@ -612,21 +1147,68 @@ async function silentlyAuthenticate(sessionId, clientAuthn, session) {
 function isLoggedIn(sessionInfo) {
     return !!(sessionInfo === null || sessionInfo === void 0 ? void 0 : sessionInfo.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.
+ */
 class Session extends EventEmitter {
+    /**
+     * Session object constructor. Typically called as follows:
+     *
+     * ```typescript
+     * const session = new Session();
+     * ```
+     *
+     * See also [getDefaultSession](https://docs.inrupt.com/developer-tools/api/javascript/solid-client-authn-browser/functions.html#getdefaultsession).
+     *
+     * @param sessionOptions The options enabling the correct instantiation of
+     * the session. Either both storages or clientAuthentication are required. For
+     * more information, see {@link ISessionOptions}.
+     * @param sessionId A string uniquely identifying the session.
+     *
+     */
     constructor(sessionOptions = {}, sessionId = undefined) {
         super();
         this.tokenRequestInProgress = false;
+        /**
+         * Triggers the login process. Note that this method will redirect the user away from your app.
+         *
+         * @param options Parameter to customize the login behaviour. In particular, two options are mandatory: `options.oidcIssuer`, the user's identity provider, and `options.redirectUrl`, the URL to which the user will be redirected after logging in their identity provider.
+         * @returns This method should redirect the user away from the app: it does not return anything. The login process is completed by {@linkcode handleIncomingRedirect}.
+         */
+        // Define these functions as properties so that they don't get accidentally re-bound.
+        // Isn't Javascript fun?
         this.login = async (options) => {
             var _a;
             await this.clientAuthentication.login({
                 sessionId: this.info.sessionId,
                 ...options,
+                // Defaults the token type to DPoP
                 tokenType: (_a = options.tokenType) !== null && _a !== void 0 ? _a : "DPoP",
             }, this.events);
+            // `login` redirects the user away from the app,
+            // so unless it throws an error, there is no code that should run afterwards
+            // (since there is no "after" in the lifetime of the script).
+            // Hence, this Promise never resolves:
             return new Promise(() => { });
         };
+        /**
+         * Fetches data using available login information. If the user is not logged in, this will behave as a regular `fetch`. The signature of this method is identical to the [canonical `fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+         *
+         * @param url The URL from which data should be fetched.
+         * @param init Optional parameters customizing the request, by specifying an HTTP method, headers, a body, etc. Follows the [WHATWG Fetch Standard](https://fetch.spec.whatwg.org/).
+         */
         this.fetch = (url, init) => this.clientAuthentication.fetch(url, init);
+        /**
+         * An internal logout function, to control whether or not the logout signal
+         * should be sent, i.e. if the logout was user-initiated or is the result of
+         * an external event.
+         *
+         * @hidden
+         */
         this.internalLogout = async (emitSignal, options) => {
+            // Clearing this value means that silent refresh will no longer be attempted.
+            // In particular, in the case of a silent authentication error it prevents
+            // from getting stuck in an authentication retries loop.
             window.localStorage.removeItem(KEY_CURRENT_SESSION);
             await this.clientAuthentication.logout(this.info.sessionId, options);
             this.info.isLoggedIn = false;
@@ -634,7 +1216,50 @@ class Session extends EventEmitter {
                 this.events.emit(solidClientAuthnCore.EVENTS.LOGOUT);
             }
         };
+        /**
+         * Logs the user out of the application.
+         *
+         * There are 2 types of logout supported by this library,
+         * `app` logout and `idp` logout.
+         *
+         * App logout will log the user out within the application
+         * by clearing any session data from the browser. It does
+         * not log the user out of their Solid identity provider,
+         * and should not redirect the user away.
+         * App logout can be performed as follows:
+         * ```typescript
+         * await session.logout({ logoutType: 'app' });
+         * ```
+         *
+         * IDP logout will log the user out of their Solid identity provider,
+         * 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 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.
+         *  state: "my-state"
+         * });
+         * ```
+         */
         this.logout = async (options) => this.internalLogout(true, options);
+        /**
+         * Completes the login process by processing the information provided by the
+         * Solid identity provider through redirect.
+         *
+         * @param options See {@see IHandleIncomingRedirectOptions}.
+         */
         this.handleIncomingRedirect = async (inputOptions = {}) => {
             var _a;
             if (this.info.isLoggedIn) {
@@ -651,17 +1276,33 @@ class Session extends EventEmitter {
                 this.setSessionInfo(sessionInfo);
                 const currentUrl = window.localStorage.getItem(KEY_CURRENT_URL);
                 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.events.emit(solidClientAuthnCore.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.events.emit(solidClientAuthnCore.EVENTS.SESSION_RESTORED, currentUrl);
                 }
             }
             else if (options.restorePreviousSession === true) {
+                // Silent authentication happens after a refresh, which means there are no
+                // OAuth params in the current location IRI. It can only succeed if a session
+                // was previously logged in, in which case its ID will be present with a known
+                // identifier in local storage.
+                // Check if we have a locally stored session ID...
                 const storedSessionId = window.localStorage.getItem(KEY_CURRENT_SESSION);
+                // ...if not, then there is no ID token, and so silent authentication cannot happen, but
+                // if we do have a stored session ID, attempt to re-authenticate now silently.
                 if (storedSessionId !== null) {
                     const attemptedSilentAuthentication = await silentlyAuthenticate(storedSessionId, this.clientAuthentication, 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
+                    // until it happens precisely. That's why the current Promise simply does not
+                    // resolve.
                     if (attemptedSilentAuthentication) {
                         return new Promise(() => { });
                     }
@@ -670,6 +1311,10 @@ class Session extends EventEmitter {
             this.tokenRequestInProgress = false;
             return sessionInfo;
         };
+        // 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, solidClientAuthnCore.buildProxyHandler(Session.prototype, "events only implements ISessionEventListener"));
         if (sessionOptions.clientAuthentication) {
             this.clientAuthentication = sessionOptions.clientAuthentication;
@@ -696,22 +1341,63 @@ class Session extends EventEmitter {
                 isLoggedIn: false,
             };
         }
+        // When a session is logged in, we want to track its ID in local storage to
+        // 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.events.on(solidClientAuthnCore.EVENTS.LOGIN, () => window.localStorage.setItem(KEY_CURRENT_SESSION, this.info.sessionId));
         this.events.on(solidClientAuthnCore.EVENTS.SESSION_EXPIRED, () => this.internalLogout(false));
         this.events.on(solidClientAuthnCore.EVENTS.ERROR, () => this.internalLogout(false));
     }
+    /**
+     * Register a callback function to be called when a user completes login.
+     *
+     * 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) {
         this.events.on(solidClientAuthnCore.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) {
         this.events.on(solidClientAuthnCore.EVENTS.LOGOUT, callback);
     }
+    /**
+     * Register a callback function to be called when a user logs out:
+     *
+     * @param callback The function called when an error occurs.
+     * @since 1.11.0
+     * @deprecated Prefer session.events.on(EVENTS.ERROR, callback)
+     */
     onError(callback) {
         this.events.on(solidClientAuthnCore.EVENTS.ERROR, callback);
     }
+    /**
+     * Register a callback function to be called when a session is restored.
+     *
+     * Note: the callback will be called with the saved value of the 'current URL'
+     * 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) {
         this.events.on(solidClientAuthnCore.EVENTS.SESSION_RESTORED, callback);
     }
+    /**
+     * Register a callback that runs when the session expires and can no longer
+     * 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) {
         this.events.on(solidClientAuthnCore.EVENTS.SESSION_EXPIRED, callback);
     }
@@ -726,41 +1412,132 @@ class Session extends EventEmitter {
     }
 }
 
+//
+// Copyright Inrupt Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to use,
+// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+// Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
 let defaultSession;
+/**
+ * Obtain the {@link Session} used when not explicitly instantiating one yourself.
+ *
+ * When using the top-level exports {@link fetch}, {@link login}, {@link logout},
+ * {@link handleIncomingRedirect}, {@link onLogin} and {@link onLogout}, these apply to an
+ * implicitly-instantiated {@link Session}.
+ * This function returns a reference to that Session in order to obtain e.g. the current user's
+ * WebID.
+ * @since 1.3.0
+ */
 function getDefaultSession() {
     if (typeof defaultSession === "undefined") {
         defaultSession = new Session();
     }
     return defaultSession;
 }
+/**
+ * This function's signature is equal to `window.fetch`, but if the current user is authenticated
+ * (see [[login]] and [[handleIncomingRedirect]]), requests made using it will include that user's
+ * credentials. If not, this will behave just like the regular `window.fetch`.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch}
+ * @since 1.3.0
+ */
+/* eslint-disable-next-line no-shadow */
 const fetch = (...args) => {
     const session = getDefaultSession();
     return session.fetch(...args);
 };
+/**
+ * Triggers the login process. Note that this method will redirect the user away from your app.
+ *
+ * @param options Parameter to customize the login behaviour. In particular, two options are mandatory: `options.oidcIssuer`, the user's identity provider, and `options.redirectUrl`, the URL to which the user will be redirected after logging in their identity provider.
+ * @returns This method should redirect the user away from the app: it does not return anything. The login process is completed by [[handleIncomingRedirect]].
+ * @since 1.3.0
+ */
 const login = (...args) => {
     const session = getDefaultSession();
     return 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`. For usage details
+ * see {@link Session.logout}.
+ *
+ * @since 1.3.0
+ */
 const logout = (...args) => {
     const session = getDefaultSession();
     return session.logout(...args);
 };
+/**
+ * Completes the login process by processing the information provided by the Solid identity provider through redirect.
+ *
+ * @param url The URL of the page handling the redirect, including the query parameters — these contain the information to process the login.
+ * @since 1.3.0
+ */
 const handleIncomingRedirect = (...args) => {
     const session = getDefaultSession();
     return session.handleIncomingRedirect(...args);
 };
+/**
+ * Register a callback function to be called when a user completes login.
+ *
+ * The callback is called when {@link handleIncomingRedirect} completes successfully.
+ * @since 1.3.0
+ *
+ * @param callback The function called when a user completes login.
+ * @deprecated Prefer events.on(EVENTS.LOGIN, callback)
+
+ */
 const onLogin = (...args) => {
     const session = getDefaultSession();
     return session.onLogin(...args);
 };
+/**
+ * Register a callback function to be called when a user logs out:
+ *
+ * @param callback The function called when a user completes logout.
+ * @since 1.3.0
+ * @deprecated Prefer events.on(EVENTS.LOGOUT, callback)
+ *
+ */
 const onLogout = (...args) => {
     const session = getDefaultSession();
     return session.onLogout(...args);
 };
+/**
+ * Register a callback function to be called when a session is restored:
+ *
+ * @param callback The function called when a session is restored.
+ * @since 1.3.0
+ * @deprecated Prefer events.on(EVENTS.SESSION_RESTORED, callback)
+ */
 const onSessionRestore = (...args) => {
     const session = getDefaultSession();
     return session.onSessionRestore(...args);
 };
+/**
+ * {@link SessionEventEmitter} instance to subscribe to events by the default session.
+ *
+ * @since 1.14.0
+ */
 const events = () => {
     return getDefaultSession().events;
 };