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

package/dist/index.js

@@ -12833,39 +12833,65 @@ var require_implementation = __commonJS({
   "../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() {
         };
@@ -12887,12 +12913,14 @@ var require_function_bind = __commonJS({
   }
 });
 
-// ../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);
   }
 });
 
@@ -13094,7 +13122,7 @@ var require_get_intrinsic = __commonJS({
       "%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);
@@ -13203,16 +13231,163 @@ var require_get_intrinsic = __commonJS({
   }
 });
 
+// ../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) {
@@ -13223,18 +13398,15 @@ var require_call_bind = __commonJS({
       }
     }
     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);
@@ -13486,6 +13658,12 @@ var require_object_inspect = __commonJS({
       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;
@@ -19834,9 +20012,9 @@ var require_queue_microtask = __commonJS({
   }
 });
 
-// ../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() {
@@ -23358,6 +23536,7 @@ var v4_default = v4;
 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",
@@ -23373,6 +23552,9 @@ var SCOPE_OFFLINE = "offline_access";
 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`);
@@ -23385,6 +23567,11 @@ var AggregateHandler = class {
     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) {
@@ -23471,12 +23658,28 @@ var AuthorizationCodeWithPkceOidcHandlerBase = class {
   }
   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"
       })
@@ -23560,18 +23763,36 @@ var SessionInfoManagerBase = class {
   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");
   }
@@ -23635,6 +23856,8 @@ async function handleRegistration(options, issuerConfig, storageUtility, clientR
     }, 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) {
@@ -23648,6 +23871,7 @@ async function handleRegistration(options, issuerConfig, storageUtility, clientR
     });
   }
   return {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     clientId: options.clientId,
     clientSecret: options.clientSecret,
     clientName: options.clientName,
@@ -23788,17 +24012,20 @@ var InMemoryStorage = class {
   }
 };
 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;
@@ -23872,7 +24099,10 @@ async function refreshAccessToken(refreshOptions, dpopKey, eventEmitter) {
 }
 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;
 };
@@ -23885,7 +24115,14 @@ async function buildAuthenticatedFetch(unauthFetch, accessToken, options) {
     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;
@@ -23903,7 +24140,12 @@ async function buildAuthenticatedFetch(unauthFetch, accessToken, options) {
         }
       }
     };
-    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(() => {
@@ -23919,7 +24161,14 @@ async function buildAuthenticatedFetch(unauthFetch, accessToken, options) {
     }
     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;
   };
@@ -23961,6 +24210,7 @@ async function registerClient(options, issuerConfig) {
   }
   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()],
@@ -23968,6 +24218,7 @@ async function registerClient(options, issuerConfig) {
     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"
@@ -24059,11 +24310,13 @@ async function getTokens(issuer2, client, data2, dpop) {
     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",
@@ -24087,7 +24340,26 @@ async function getBearerToken(redirectUrl) {
   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);
@@ -24108,6 +24380,13 @@ async function getBearerToken(redirectUrl) {
       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) {
@@ -24143,6 +24422,8 @@ async function refresh(refreshToken, issuer2, client, dpopKey) {
   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)) {
@@ -24179,13 +24460,28 @@ function removeOidcQueryParam(redirectUrl) {
   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({}));
@@ -24219,6 +24515,7 @@ var ClientAuthentication2 = class extends 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
       });
@@ -24235,7 +24532,7 @@ var ClientAuthentication2 = class extends ClientAuthentication {
         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,
@@ -24243,13 +24540,13 @@ var ClientAuthentication2 = class extends ClientAuthentication {
           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");
@@ -24259,6 +24556,11 @@ var ClientAuthentication2 = class extends ClientAuthentication {
     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) {
@@ -24291,7 +24593,13 @@ var OidcLoginHandler = class {
     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,
@@ -24312,6 +24620,9 @@ var AuthorizationCodeWithPkceOidcHandler = class extends AuthorizationCodeWithPk
       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"
@@ -24321,7 +24632,9 @@ var AuthorizationCodeWithPkceOidcHandler = class extends AuthorizationCodeWithPk
       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()
       });
@@ -24436,12 +24749,19 @@ var IssuerConfigFetcher = class _IssuerConfigFetcher {
     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());
@@ -24506,9 +24826,16 @@ var SessionInfoManager = class extends SessionInfoManagerBase {
       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);
   }
@@ -24574,6 +24901,8 @@ var AuthCodeRedirectHandler = class {
     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
@@ -24650,13 +24979,21 @@ var ClientRegistrar = class {
     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 {
@@ -24677,6 +25014,9 @@ var ClientRegistrar = class {
         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;
@@ -24745,6 +25085,8 @@ function getClientAuthenticationWithDependencies(dependencies3) {
   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);
@@ -24773,6 +25115,21 @@ function isLoggedIn(sessionInfo) {
   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;
@@ -24781,6 +25138,7 @@ var Session = class _Session extends import_events2.default {
       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(() => {
@@ -24857,18 +25215,55 @@ var Session = class _Session extends import_events2.default {
     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);
   }