@pod-os/core 0.11.1-329cf1f.0 → 0.11.1-62e1055.0

package/lib/index.js

@@ -12860,39 +12860,65 @@ var PodOS = (() => {
     "../node_modules/function-bind/implementation.js"(exports, module3) {
       "use strict";
       var ERROR_MESSAGE = "Function.prototype.bind called on incompatible ";
-      var slice = Array.prototype.slice;
       var toStr = Object.prototype.toString;
+      var max2 = Math.max;
       var funcType = "[object Function]";
+      var concatty = function concatty2(a, b) {
+        var arr = [];
+        for (var i = 0; i < a.length; i += 1) {
+          arr[i] = a[i];
+        }
+        for (var j = 0; j < b.length; j += 1) {
+          arr[j + a.length] = b[j];
+        }
+        return arr;
+      };
+      var slicy = function slicy2(arrLike, offset3) {
+        var arr = [];
+        for (var i = offset3 || 0, j = 0; i < arrLike.length; i += 1, j += 1) {
+          arr[j] = arrLike[i];
+        }
+        return arr;
+      };
+      var joiny = function(arr, joiner) {
+        var str = "";
+        for (var i = 0; i < arr.length; i += 1) {
+          str += arr[i];
+          if (i + 1 < arr.length) {
+            str += joiner;
+          }
+        }
+        return str;
+      };
       module3.exports = function bind(that) {
         var target5 = this;
-        if (typeof target5 !== "function" || toStr.call(target5) !== funcType) {
+        if (typeof target5 !== "function" || toStr.apply(target5) !== funcType) {
           throw new TypeError(ERROR_MESSAGE + target5);
         }
-        var args = slice.call(arguments, 1);
+        var args = slicy(arguments, 1);
         var bound;
         var binder = function() {
           if (this instanceof bound) {
             var result5 = target5.apply(
               this,
-              args.concat(slice.call(arguments))
+              concatty(args, arguments)
             );
             if (Object(result5) === result5) {
               return result5;
             }
             return this;
-          } else {
-            return target5.apply(
-              that,
-              args.concat(slice.call(arguments))
-            );
           }
+          return target5.apply(
+            that,
+            concatty(args, arguments)
+          );
         };
-        var boundLength = Math.max(0, target5.length - args.length);
+        var boundLength = max2(0, target5.length - args.length);
         var boundArgs = [];
         for (var i = 0; i < boundLength; i++) {
-          boundArgs.push("$" + i);
+          boundArgs[i] = "$" + i;
         }
-        bound = Function("binder", "return function (" + boundArgs.join(",") + "){ return binder.apply(this,arguments); }")(binder);
+        bound = Function("binder", "return function (" + joiny(boundArgs, ",") + "){ return binder.apply(this,arguments); }")(binder);
         if (target5.prototype) {
           var Empty = function Empty2() {
           };
@@ -12914,12 +12940,14 @@ var PodOS = (() => {
     }
   });
 
-  // ../node_modules/has/src/index.js
-  var require_src = __commonJS({
-    "../node_modules/has/src/index.js"(exports, module3) {
+  // ../node_modules/hasown/index.js
+  var require_hasown = __commonJS({
+    "../node_modules/hasown/index.js"(exports, module3) {
       "use strict";
+      var call = Function.prototype.call;
+      var $hasOwn = Object.prototype.hasOwnProperty;
       var bind = require_function_bind();
-      module3.exports = bind.call(Function.call, Object.prototype.hasOwnProperty);
+      module3.exports = bind.call(call, $hasOwn);
     }
   });
 
@@ -13121,7 +13149,7 @@ var PodOS = (() => {
         "%WeakSetPrototype%": ["WeakSet", "prototype"]
       };
       var bind = require_function_bind();
-      var hasOwn = require_src();
+      var hasOwn = require_hasown();
       var $concat = bind.call(Function.call, Array.prototype.concat);
       var $spliceApply = bind.call(Function.apply, Array.prototype.splice);
       var $replace = bind.call(Function.call, String.prototype.replace);
@@ -13230,16 +13258,163 @@ var PodOS = (() => {
     }
   });
 
+  // ../node_modules/has-property-descriptors/index.js
+  var require_has_property_descriptors = __commonJS({
+    "../node_modules/has-property-descriptors/index.js"(exports, module3) {
+      "use strict";
+      var GetIntrinsic = require_get_intrinsic();
+      var $defineProperty = GetIntrinsic("%Object.defineProperty%", true);
+      var hasPropertyDescriptors = function hasPropertyDescriptors2() {
+        if ($defineProperty) {
+          try {
+            $defineProperty({}, "a", { value: 1 });
+            return true;
+          } catch (e) {
+            return false;
+          }
+        }
+        return false;
+      };
+      hasPropertyDescriptors.hasArrayLengthDefineBug = function hasArrayLengthDefineBug() {
+        if (!hasPropertyDescriptors()) {
+          return null;
+        }
+        try {
+          return $defineProperty([], "length", { value: 1 }).length !== 1;
+        } catch (e) {
+          return true;
+        }
+      };
+      module3.exports = hasPropertyDescriptors;
+    }
+  });
+
+  // ../node_modules/gopd/index.js
+  var require_gopd = __commonJS({
+    "../node_modules/gopd/index.js"(exports, module3) {
+      "use strict";
+      var GetIntrinsic = require_get_intrinsic();
+      var $gOPD = GetIntrinsic("%Object.getOwnPropertyDescriptor%", true);
+      if ($gOPD) {
+        try {
+          $gOPD([], "length");
+        } catch (e) {
+          $gOPD = null;
+        }
+      }
+      module3.exports = $gOPD;
+    }
+  });
+
+  // ../node_modules/define-data-property/index.js
+  var require_define_data_property = __commonJS({
+    "../node_modules/define-data-property/index.js"(exports, module3) {
+      "use strict";
+      var hasPropertyDescriptors = require_has_property_descriptors()();
+      var GetIntrinsic = require_get_intrinsic();
+      var $defineProperty = hasPropertyDescriptors && GetIntrinsic("%Object.defineProperty%", true);
+      if ($defineProperty) {
+        try {
+          $defineProperty({}, "a", { value: 1 });
+        } catch (e) {
+          $defineProperty = false;
+        }
+      }
+      var $SyntaxError = GetIntrinsic("%SyntaxError%");
+      var $TypeError = GetIntrinsic("%TypeError%");
+      var gopd = require_gopd();
+      module3.exports = function defineDataProperty(obj, property3, value6) {
+        if (!obj || typeof obj !== "object" && typeof obj !== "function") {
+          throw new $TypeError("`obj` must be an object or a function`");
+        }
+        if (typeof property3 !== "string" && typeof property3 !== "symbol") {
+          throw new $TypeError("`property` must be a string or a symbol`");
+        }
+        if (arguments.length > 3 && typeof arguments[3] !== "boolean" && arguments[3] !== null) {
+          throw new $TypeError("`nonEnumerable`, if provided, must be a boolean or null");
+        }
+        if (arguments.length > 4 && typeof arguments[4] !== "boolean" && arguments[4] !== null) {
+          throw new $TypeError("`nonWritable`, if provided, must be a boolean or null");
+        }
+        if (arguments.length > 5 && typeof arguments[5] !== "boolean" && arguments[5] !== null) {
+          throw new $TypeError("`nonConfigurable`, if provided, must be a boolean or null");
+        }
+        if (arguments.length > 6 && typeof arguments[6] !== "boolean") {
+          throw new $TypeError("`loose`, if provided, must be a boolean");
+        }
+        var nonEnumerable = arguments.length > 3 ? arguments[3] : null;
+        var nonWritable = arguments.length > 4 ? arguments[4] : null;
+        var nonConfigurable = arguments.length > 5 ? arguments[5] : null;
+        var loose = arguments.length > 6 ? arguments[6] : false;
+        var desc = !!gopd && gopd(obj, property3);
+        if ($defineProperty) {
+          $defineProperty(obj, property3, {
+            configurable: nonConfigurable === null && desc ? desc.configurable : !nonConfigurable,
+            enumerable: nonEnumerable === null && desc ? desc.enumerable : !nonEnumerable,
+            value: value6,
+            writable: nonWritable === null && desc ? desc.writable : !nonWritable
+          });
+        } else if (loose || !nonEnumerable && !nonWritable && !nonConfigurable) {
+          obj[property3] = value6;
+        } else {
+          throw new $SyntaxError("This environment does not support defining a property as non-configurable, non-writable, or non-enumerable.");
+        }
+      };
+    }
+  });
+
+  // ../node_modules/set-function-length/index.js
+  var require_set_function_length = __commonJS({
+    "../node_modules/set-function-length/index.js"(exports, module3) {
+      "use strict";
+      var GetIntrinsic = require_get_intrinsic();
+      var define2 = require_define_data_property();
+      var hasDescriptors = require_has_property_descriptors()();
+      var gOPD = require_gopd();
+      var $TypeError = GetIntrinsic("%TypeError%");
+      var $floor = GetIntrinsic("%Math.floor%");
+      module3.exports = function setFunctionLength(fn2, length2) {
+        if (typeof fn2 !== "function") {
+          throw new $TypeError("`fn` is not a function");
+        }
+        if (typeof length2 !== "number" || length2 < 0 || length2 > 4294967295 || $floor(length2) !== length2) {
+          throw new $TypeError("`length` must be a positive 32-bit integer");
+        }
+        var loose = arguments.length > 2 && !!arguments[2];
+        var functionLengthIsConfigurable = true;
+        var functionLengthIsWritable = true;
+        if ("length" in fn2 && gOPD) {
+          var desc = gOPD(fn2, "length");
+          if (desc && !desc.configurable) {
+            functionLengthIsConfigurable = false;
+          }
+          if (desc && !desc.writable) {
+            functionLengthIsWritable = false;
+          }
+        }
+        if (functionLengthIsConfigurable || functionLengthIsWritable || !loose) {
+          if (hasDescriptors) {
+            define2(fn2, "length", length2, true, true);
+          } else {
+            define2(fn2, "length", length2);
+          }
+        }
+        return fn2;
+      };
+    }
+  });
+
   // ../node_modules/call-bind/index.js
   var require_call_bind = __commonJS({
     "../node_modules/call-bind/index.js"(exports, module3) {
       "use strict";
       var bind = require_function_bind();
       var GetIntrinsic = require_get_intrinsic();
+      var setFunctionLength = require_set_function_length();
+      var $TypeError = GetIntrinsic("%TypeError%");
       var $apply = GetIntrinsic("%Function.prototype.apply%");
       var $call = GetIntrinsic("%Function.prototype.call%");
       var $reflectApply = GetIntrinsic("%Reflect.apply%", true) || bind.call($call, $apply);
-      var $gOPD = GetIntrinsic("%Object.getOwnPropertyDescriptor%", true);
       var $defineProperty = GetIntrinsic("%Object.defineProperty%", true);
       var $max = GetIntrinsic("%Math.max%");
       if ($defineProperty) {
@@ -13250,18 +13425,15 @@ var PodOS = (() => {
         }
       }
       module3.exports = function callBind(originalFunction) {
-        var func = $reflectApply(bind, $call, arguments);
-        if ($gOPD && $defineProperty) {
-          var desc = $gOPD(func, "length");
-          if (desc.configurable) {
-            $defineProperty(
-              func,
-              "length",
-              { value: 1 + $max(0, originalFunction.length - (arguments.length - 1)) }
-            );
-          }
+        if (typeof originalFunction !== "function") {
+          throw new $TypeError("a function is required");
         }
-        return func;
+        var func = $reflectApply(bind, $call, arguments);
+        return setFunctionLength(
+          func,
+          1 + $max(0, originalFunction.length - (arguments.length - 1)),
+          true
+        );
       };
       var applyBind = function applyBind2() {
         return $reflectApply(bind, $apply, arguments);
@@ -13513,6 +13685,12 @@ var PodOS = (() => {
         if (isString(obj)) {
           return markBoxed(inspect(String(obj)));
         }
+        if (typeof window !== "undefined" && obj === window) {
+          return "{ [object Window] }";
+        }
+        if (obj === global) {
+          return "{ [object globalThis] }";
+        }
         if (!isDate(obj) && !isRegExp(obj)) {
           var ys = arrObjKeys(obj, inspect);
           var isPlainObject = gPO ? gPO(obj) === Object.prototype : obj instanceof Object || obj.constructor === Object;
@@ -28317,9 +28495,9 @@ var PodOS = (() => {
     }
   });
 
-  // ../node_modules/cross-fetch/dist/browser-ponyfill.js
+  // ../node_modules/rdflib/node_modules/cross-fetch/dist/browser-ponyfill.js
   var require_browser_ponyfill = __commonJS({
-    "../node_modules/cross-fetch/dist/browser-ponyfill.js"(exports, module3) {
+    "../node_modules/rdflib/node_modules/cross-fetch/dist/browser-ponyfill.js"(exports, module3) {
       var global3 = typeof self !== "undefined" ? self : exports;
       var __self__ = function() {
         function F() {
@@ -31857,6 +32035,7 @@ var PodOS = (() => {
   var SOLID_CLIENT_AUTHN_KEY_PREFIX = "solidClientAuthn:";
   var PREFERRED_SIGNING_ALG = ["ES256", "RS256"];
   var EVENTS = {
+    // Note that an `error` events MUST be listened to: https://nodejs.org/dist/latest-v16.x/docs/api/events.html#error-events.
     ERROR: "error",
     LOGIN: "login",
     LOGOUT: "logout",
@@ -31872,6 +32051,9 @@ var PodOS = (() => {
   var SCOPE_WEBID = "webid";
   var DEFAULT_SCOPES = [SCOPE_OPENID, SCOPE_OFFLINE, SCOPE_WEBID].join(" ");
   var buildProxyHandler = (toExclude, errorMessage) => ({
+    // This proxy is only a temporary measure until Session no longer extends
+    // SessionEventEmitter, and the proxying is no longer necessary.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     get(target5, prop, receiver2) {
       if (!Object.getOwnPropertyNames(import_events.EventEmitter).includes(prop) && Object.getOwnPropertyNames(toExclude).includes(prop)) {
         throw new Error(`${errorMessage}: [${prop}] is not supported`);
@@ -31884,6 +32066,11 @@ var PodOS = (() => {
       this.handleables = handleables;
       this.handleables = handleables;
     }
+    /**
+     * Helper function that will asynchronously determine the proper handler to use. If multiple
+     * handlers can handle, it will choose the first one in the list
+     * @param params Paramerters to feed to the handler
+     */
     async getProperHandler(params2) {
       const canHandleList = await Promise.all(this.handleables.map((handleable) => handleable.canHandle(...params2)));
       for (let i = 0; i < canHandleList.length; i += 1) {
@@ -31970,12 +32157,28 @@ var PodOS = (() => {
     }
     async handleRedirect({ oidcLoginOptions, state: state2, codeVerifier, targetUrl: targetUrl3 }) {
       await Promise.all([
+        // We use the OAuth 'state' value (which should be crypto-random) as
+        // the key in our storage to store our actual SessionID. We do this
+        // 'cos we'll need to lookup our session information again when the
+        // browser is redirected back to us (i.e. the OAuth client
+        // application) from the Authorization Server.
+        // We don't want to use our session ID as the OAuth 'state' value, as
+        // that session ID can be any developer-specified value, and therefore
+        // may not be appropriate (since the OAuth 'state' value should really
+        // be an unguessable crypto-random value).
+        // eslint-disable-next-line no-underscore-dangle
         this.storageUtility.setForUser(state2, {
           sessionId: oidcLoginOptions.sessionId
         }),
+        // Store our login-process state using the session ID as the key.
+        // Strictly speaking, this indirection from our OAuth state value to
+        // our session ID is unnecessary, but it provides a slightly cleaner
+        // separation of concerns.
         this.storageUtility.setForUser(oidcLoginOptions.sessionId, {
+          // eslint-disable-next-line no-underscore-dangle
           codeVerifier,
           issuer: oidcLoginOptions.issuer.toString(),
+          // The redirect URL is read after redirect, so it must be stored now.
           redirectUrl: oidcLoginOptions.redirectUrl,
           dpop: oidcLoginOptions.dpop ? "true" : "false"
         })
@@ -32059,18 +32262,36 @@ var PodOS = (() => {
     get(_) {
       throw new Error("Not implemented");
     }
+    // eslint-disable-next-line class-methods-use-this
     async getAll() {
       throw new Error("Not implemented");
     }
+    /**
+     * 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);
     }
+    /**
+     * Registers a new session, so that its ID can be retrieved.
+     * @param sessionId
+     */
     async register(_sessionId) {
       throw new Error("Not implemented");
     }
+    /**
+     * Returns all the registered session IDs. Differs from getAll, which also
+     * returns additional session information.
+     */
     async getRegisteredSessionIdAll() {
       throw new Error("Not implemented");
     }
+    /**
+     * Deletes all information about all sessions, including their registrations.
+     */
     async clearAll() {
       throw new Error("Not implemented");
     }
@@ -32134,6 +32355,8 @@ var PodOS = (() => {
       }, issuerConfig);
     }
     await storageUtility.setForUser(options.sessionId, {
+      // If the client is either static or solid-oidc compliant, its client ID cannot be undefined.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       clientId: options.clientId
     });
     if (options.clientSecret) {
@@ -32147,6 +32370,7 @@ var PodOS = (() => {
       });
     }
     return {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       clientId: options.clientId,
       clientSecret: options.clientSecret,
       clientName: options.clientName,
@@ -32287,17 +32511,20 @@ var PodOS = (() => {
     }
   };
   var ConfigurationError = class extends Error {
+    /* istanbul ignore next */
     constructor(message4) {
       super(message4);
     }
   };
   var InvalidResponseError = class extends Error {
+    /* istanbul ignore next */
     constructor(missingFields) {
       super(`Invalid response from OIDC provider: missing fields ${missingFields}`);
       this.missingFields = missingFields;
     }
   };
   var OidcProviderError = class extends Error {
+    /* istanbul ignore next */
     constructor(message4, error5, errorDescription) {
       super(message4);
       this.error = error5;
@@ -32371,7 +32598,10 @@ var PodOS = (() => {
   }
   var computeRefreshDelay = (expiresIn) => {
     if (expiresIn !== void 0) {
-      return expiresIn - REFRESH_BEFORE_EXPIRATION_SECONDS > 0 ? expiresIn - REFRESH_BEFORE_EXPIRATION_SECONDS : expiresIn;
+      return expiresIn - REFRESH_BEFORE_EXPIRATION_SECONDS > 0 ? (
+        // We want to refresh the token 5 seconds before they actually expire.
+        expiresIn - REFRESH_BEFORE_EXPIRATION_SECONDS
+      ) : expiresIn;
     }
     return DEFAULT_EXPIRATION_TIME_SECONDS;
   };
@@ -32384,7 +32614,14 @@ var PodOS = (() => {
       const proactivelyRefreshToken = async () => {
         var _a2, _b, _c, _d;
         try {
-          const { accessToken: refreshedAccessToken, refreshToken, expiresIn } = await refreshAccessToken(currentRefreshOptions, options.dpopKey, options.eventEmitter);
+          const { accessToken: refreshedAccessToken, refreshToken, expiresIn } = await refreshAccessToken(
+            currentRefreshOptions,
+            // If currentRefreshOptions is defined, options is necessarily defined too.
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            options.dpopKey,
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            options.eventEmitter
+          );
           currentAccessToken = refreshedAccessToken;
           if (refreshToken !== void 0) {
             currentRefreshOptions.refreshToken = refreshToken;
@@ -32402,7 +32639,12 @@ var PodOS = (() => {
           }
         }
       };
-      latestTimeout = setTimeout(proactivelyRefreshToken, computeRefreshDelay(options.expiresIn) * 1e3);
+      latestTimeout = setTimeout(
+        proactivelyRefreshToken,
+        // If currentRefreshOptions is defined, options is necessarily defined too.
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        computeRefreshDelay(options.expiresIn) * 1e3
+      );
       (_a = options.eventEmitter) === null || _a === void 0 ? void 0 : _a.emit(EVENTS.TIMEOUT_SET, latestTimeout);
     } else if (options !== void 0 && options.eventEmitter !== void 0) {
       const expirationTimeout = setTimeout(() => {
@@ -32418,7 +32660,14 @@ var PodOS = (() => {
       }
       const hasBeenRedirected = response6.url !== url7;
       if (hasBeenRedirected && (options === null || options === void 0 ? void 0 : options.dpopKey) !== void 0) {
-        response6 = await makeAuthenticatedRequest(unauthFetch, currentAccessToken, response6.url, requestInit, options.dpopKey);
+        response6 = await makeAuthenticatedRequest(
+          unauthFetch,
+          currentAccessToken,
+          // Replace the original target IRI (`url`) by the redirection target
+          response6.url,
+          requestInit,
+          options.dpopKey
+        );
       }
       return response6;
     };
@@ -32460,6 +32709,7 @@ var PodOS = (() => {
     }
     const signingAlg = determineSigningAlg(issuerConfig.idTokenSigningAlgValuesSupported, PREFERRED_SIGNING_ALG);
     const config = {
+      /* eslint-disable camelcase */
       client_name: options.clientName,
       application_type: "web",
       redirect_uris: [(_a = options.redirectUrl) === null || _a === void 0 ? void 0 : _a.toString()],
@@ -32467,6 +32717,7 @@ var PodOS = (() => {
       token_endpoint_auth_method: "client_secret_basic",
       id_token_signed_response_alg: signingAlg,
       grant_types: ["authorization_code", "refresh_token"]
+      /* eslint-enable camelcase */
     };
     const headers = {
       "Content-Type": "application/json"
@@ -32558,11 +32809,13 @@ var PodOS = (() => {
       headers.Authorization = `Basic ${btoa(`${client.clientId}:${client.clientSecret}`)}`;
     }
     const requestBody = {
+      /* eslint-disable camelcase */
       grant_type: data2.grantType,
       redirect_uri: data2.redirectUrl,
       code: data2.code,
       code_verifier: data2.codeVerifier,
       client_id: client.clientId
+      /* eslint-enable camelcase */
     };
     const tokenRequestInit = {
       method: "POST",
@@ -32586,7 +32839,26 @@ var PodOS = (() => {
     let signinResponse;
     try {
       const client = new import_oidc_client.OidcClient({
+        // TODO: We should look at the various interfaces being used for storage,
+        //  i.e. between oidc-client-js (WebStorageStoreState), localStorage
+        //  (which has an interface Storage), and our own proprietary interface
+        //  IStorage - i.e. we should really just be using the browser Web Storage
+        //  API, e.g. "stateStore: window.localStorage,".
+        // We are instantiating a new instance here, so the only value we need to
+        // explicitly provide is the response mode (default otherwise will look
+        // for a hash '#' fragment!).
+        // eslint-disable-next-line camelcase
         response_mode: "query",
+        // 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.
+        // TODO: Note that this is heavy-handed, and that this userinfo check
+        //  verifies that the `sub` claim in the id token you get along with the
+        //  access token matches the sub claim associated with the access token at
+        //  the userinfo endpoint.
+        // That is a useful check, and in the future it should be only disabled
+        // against NSS, and not in general.
+        // Issue tracker: https://github.com/solid/node-solid-server/issues/1490
         loadUserInfo: false
       });
       signinResponse = await client.processSigninResponse(redirectUrl);
@@ -32607,6 +32879,13 @@ var PodOS = (() => {
         accessToken: signinResponse.access_token,
         idToken: signinResponse.id_token,
         webId,
+        // Although not a field in the TypeScript response interface, the refresh
+        // token (which can optionally come back with the access token (if, as per
+        // the OAuth2 spec, we requested one using the scope of 'offline_access')
+        // will be included in the signin response object.
+        // eslint-disable-next-line camelcase
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
         refreshToken: signinResponse.refresh_token
       };
     } catch (err) {
@@ -32642,6 +32921,8 @@ var PodOS = (() => {
     let authHeader = {};
     if (client.clientSecret !== void 0) {
       authHeader = {
+        // We assume that client_secret_basic is the client authentication method.
+        // TODO: Get the authentication method from the IClient configuration object.
         Authorization: `Basic ${btoa(`${client.clientId}:${client.clientSecret}`)}`
       };
     } else if (isValidUrl2(client.clientId)) {
@@ -32678,13 +32959,28 @@ var PodOS = (() => {
     cleanedUrl.searchParams.delete("code");
     cleanedUrl.searchParams.delete("state");
     cleanedUrl.hash = "";
-    if (redirectUrl.includes(`${cleanedUrl.origin}/`)) {
+    if (
+      // The trailing slash is present in the original redirect URL
+      redirectUrl.includes(`${cleanedUrl.origin}/`)
+    ) {
       return cleanedUrl.href;
     }
-    return `${cleanedUrl.origin}${cleanedUrl.href.substring(cleanedUrl.origin.length + 1)}`;
+    return `${cleanedUrl.origin}${cleanedUrl.href.substring(
+      // Adds 1 to the origin length to remove the trailing slash
+      cleanedUrl.origin.length + 1
+    )}`;
   }
   async function clearOidcPersistentStorage() {
     const client = new import_oidc_client.OidcClient({
+      // TODO: We should look at the various interfaces being used for storage,
+      //  i.e. between oidc-client-js (WebStorageStoreState), localStorage
+      //  (which has an interface Storage), and our own proprietary interface
+      //  IStorage - i.e. we should really just be using the browser Web Storage
+      //  API, e.g. "stateStore: window.localStorage,".
+      // We are instantiating a new instance here, so the only value we need to
+      // explicitly provide is the response mode (default otherwise will look
+      // for a hash '#' fragment!).
+      // eslint-disable-next-line camelcase
       response_mode: "query"
     });
     await client.clearStaleState(new import_oidc_client.WebStorageStateStore({}));
@@ -32718,6 +33014,7 @@ var PodOS = (() => {
         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
         });
@@ -32734,7 +33031,7 @@ var PodOS = (() => {
           const redirectInfo = await this.redirectHandler.handle(url7, eventEmitter);
           this.fetch = redirectInfo.fetch.bind(window);
           this.boundLogout = redirectInfo.getLogoutUrl;
-          this.cleanUrlAfterRedirect(url7);
+          await this.cleanUrlAfterRedirect(url7);
           return {
             isLoggedIn: redirectInfo.isLoggedIn,
             webId: redirectInfo.webId,
@@ -32742,13 +33039,13 @@ var PodOS = (() => {
             expirationDate: redirectInfo.expirationDate
           };
         } catch (err) {
-          this.cleanUrlAfterRedirect(url7);
+          await this.cleanUrlAfterRedirect(url7);
           eventEmitter.emit(EVENTS.ERROR, "redirect", err);
           return void 0;
         }
       };
     }
-    cleanUrlAfterRedirect(url7) {
+    async cleanUrlAfterRedirect(url7) {
       const cleanedUpUrl = new URL(url7);
       cleanedUpUrl.searchParams.delete("state");
       cleanedUpUrl.searchParams.delete("code");
@@ -32758,6 +33055,11 @@ var PodOS = (() => {
       cleanedUpUrl.searchParams.delete("error_description");
       cleanedUpUrl.searchParams.delete("iss");
       window.history.replaceState(null, "", cleanedUpUrl.toString());
+      while (window.location.href !== cleanedUpUrl.href) {
+        await new Promise((resolve) => {
+          setTimeout(() => resolve(), 1);
+        });
+      }
     }
   };
   function hasIssuer(options) {
@@ -32790,7 +33092,13 @@ var PodOS = (() => {
       const issuerConfig = await this.issuerConfigFetcher.fetchConfig(options.oidcIssuer);
       const clientRegistration = await handleRegistration(options, issuerConfig, this.storageUtility, this.clientRegistrar);
       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,
@@ -32811,6 +33119,9 @@ var PodOS = (() => {
         response_type: "code",
         scope: 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"
@@ -32820,7 +33131,9 @@ var PodOS = (() => {
         const signingRequest = await oidcClientLibrary.createSigninRequest();
         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()
         });
@@ -32935,12 +33248,19 @@ var PodOS = (() => {
       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(issuer2) {
       return `issuerConfig:${issuer2}`;
     }
     async fetchConfig(issuer2) {
       let issuerConfig;
-      const openIdConfigUrl = new URL(WELL_KNOWN_OPENID_CONFIG, issuer2.endsWith("/") ? issuer2 : `${issuer2}/`).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.
+        issuer2.endsWith("/") ? issuer2 : `${issuer2}/`
+      ).href;
       const issuerConfigRequestBody = await fetch2.call(globalThis, openIdConfigUrl);
       try {
         issuerConfig = processConfig(await issuerConfigRequestBody.json());
@@ -33005,9 +33325,16 @@ var PodOS = (() => {
         issuer: issuer2,
         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 clear2(sessionId, this.storageUtility);
     }
@@ -33073,6 +33400,8 @@ var PodOS = (() => {
       if (isDpop) {
         tokens = await 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: url7.searchParams.get("code"),
           codeVerifier,
           redirectUrl: storedRedirectIri
@@ -33149,13 +33478,21 @@ var PodOS = (() => {
       this.storageUtility = storageUtility;
     }
     async getClient(options, issuerConfig) {
-      const [storedClientId, storedClientSecret] = await Promise.all([
+      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 {
@@ -33176,6 +33513,9 @@ var PodOS = (() => {
           infoToSave.idTokenSignedResponseAlg = 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;
@@ -33244,6 +33584,8 @@ var PodOS = (() => {
     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 ClientAuthentication2(loginHandler, redirectHandler, new IWaterfallLogoutHandler(sessionInfoManager, redirector), sessionInfoManager, issuerConfigFetcher);
@@ -33272,6 +33614,21 @@ var PodOS = (() => {
     return !!(sessionInfo === null || sessionInfo === void 0 ? void 0 : sessionInfo.isLoggedIn);
   }
   var Session = class _Session extends import_events2.default {
+    /**
+     * 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 = void 0) {
       super();
       this.tokenRequestInProgress = false;
@@ -33280,6 +33637,7 @@ var PodOS = (() => {
         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);
         return new Promise(() => {
@@ -33356,18 +33714,55 @@ var PodOS = (() => {
       this.events.on(EVENTS.SESSION_EXPIRED, () => this.internalLogout(false));
       this.events.on(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(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(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(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(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(EVENTS.SESSION_EXPIRED, callback);
     }