@pod-os/elements 0.32.1-rc.0fc2066.0 → 0.32.1-rc.494c386.0

package/dist/cjs/ion-icon_31.cjs.entry.js

@@ -2612,160 +2612,6 @@ const requestDynamicClientRegistration = async (registration_endpoint, client_de
     });
 };
 
-/**
- * A simple IndexedDB wrapper
- */
-class SessionDatabase {
-    dbName;
-    storeName;
-    dbVersion;
-    db = null;
-    /**
-     * Creates a new instance
-     * @param dbName The name of the IndexedDB database
-     * @param storeName The name of the object store
-     * @param dbVersion The database version
-     */
-    constructor(dbName = 'soidc', storeName = 'session', dbVersion = 1) {
-        this.dbName = dbName;
-        this.storeName = storeName;
-        this.dbVersion = dbVersion;
-    }
-    /**
-     * Initializes the IndexedDB database
-     * @returns Promise that resolves when the database is ready
-     */
-    async init() {
-        return new Promise((resolve, reject) => {
-            const request = indexedDB.open(this.dbName, this.dbVersion);
-            request.onerror = (event) => {
-                reject(new Error(`Database error: ${event.target.error}`));
-            };
-            request.onsuccess = (event) => {
-                this.db = event.target.result;
-                resolve(this);
-            };
-            request.onupgradeneeded = (event) => {
-                const db = event.target.result;
-                // Check if the object store already exists, if not create it
-                if (!db.objectStoreNames.contains(this.storeName)) {
-                    db.createObjectStore(this.storeName);
-                }
-            };
-        });
-    }
-    /**
-     * Stores any value in the database with the given ID as key
-     * @param id The identifier/key for the value
-     * @param value The value to store
-     */
-    async setItem(id, value) {
-        if (!this.db) {
-            await this.init();
-        }
-        return new Promise((resolve, reject) => {
-            const transaction = this.db.transaction(this.storeName, 'readwrite');
-            // Handle transation
-            transaction.oncomplete = () => {
-                resolve();
-            };
-            transaction.onerror = (event) => {
-                reject(new Error(`Transaction error for setItem(${id},...): ${event.target.error}`));
-            };
-            transaction.onabort = (event) => {
-                reject(new Error(`Transaction aborted for setItem(${id},...): ${event.target.error}`));
-            };
-            // Perform the request within the transaction
-            const store = transaction.objectStore(this.storeName);
-            store.put(value, id);
-        });
-    }
-    /**
-      * Retrieves a value from the database by ID
-      * @param id The identifier/key for the value
-      * @returns The stored value or null if not found
-      */
-    async getItem(id) {
-        if (!this.db) {
-            await this.init();
-        }
-        return new Promise((resolve, reject) => {
-            const transaction = this.db.transaction(this.storeName, 'readonly');
-            // Handle transation
-            transaction.onerror = (event) => {
-                reject(new Error(`Transaction error for getItem(${id}): ${event.target.error}`));
-            };
-            transaction.onabort = (event) => {
-                reject(new Error(`Transaction aborted for getItem(${id}): ${event.target.error}`));
-            };
-            // Perform the request within the transaction
-            const store = transaction.objectStore(this.storeName);
-            const request = store.get(id);
-            request.onsuccess = () => {
-                resolve(request.result || null);
-            };
-        });
-    }
-    /**
-     * Removes an item from the database
-     * @param id The identifier of the item to remove
-     */
-    async deleteItem(id) {
-        if (!this.db) {
-            await this.init();
-        }
-        return new Promise((resolve, reject) => {
-            const transaction = this.db.transaction(this.storeName, 'readwrite');
-            // Handle transation
-            transaction.oncomplete = () => {
-                resolve();
-            };
-            transaction.onerror = (event) => {
-                reject(new Error(`Transaction error for deleteItem(${id}): ${event.target.error}`));
-            };
-            transaction.onabort = (event) => {
-                reject(new Error(`Transaction aborted for deleteItem(${id}): ${event.target.error}`));
-            };
-            // Perform the request within the transaction
-            const store = transaction.objectStore(this.storeName);
-            store.delete(id);
-        });
-    }
-    /**
-     * Clears all items from the database
-     */
-    async clear() {
-        if (!this.db) {
-            await this.init();
-        }
-        return new Promise((resolve, reject) => {
-            const transaction = this.db.transaction(this.storeName, 'readwrite');
-            // Handle transation
-            transaction.oncomplete = () => {
-                resolve();
-            };
-            transaction.onerror = (event) => {
-                reject(new Error(`Transaction error for clear(): ${event.target.error}`));
-            };
-            transaction.onabort = (event) => {
-                reject(new Error(`Transaction aborted for clear(): ${event.target.error}`));
-            };
-            // Perform the request within the transaction
-            const store = transaction.objectStore(this.storeName);
-            store.clear();
-        });
-    }
-    /**
-     * Closes the database connection
-     */
-    close() {
-        if (this.db) {
-            this.db.close();
-            this.db = null;
-        }
-    }
-}
-
 /**
  * Login with the idp, using a provided `client_id` or dynamic client registration if none provided.
  *
@@ -2789,7 +2635,7 @@ const redirectForLogin = async (idp, redirect_uri, client_details) => {
     const issuer = openid_configuration["issuer"];
     const trim_trailing_slash = (url) => (url.endsWith('/') ? url.slice(0, -1) : url);
     if (trim_trailing_slash(idp) !== trim_trailing_slash(issuer)) { // expected idp matches received issuer mod trailing slash?
-        throw new Error("RFC 9207 - iss != idp - " + issuer + " != " + idp);
+        throw new Error("RFC 9207 - iss !== idp - " + issuer + " !== " + idp);
     }
     sessionStorage.setItem("idp", issuer);
     // remember token endpoint
@@ -2810,7 +2656,12 @@ const redirectForLogin = async (idp, redirect_uri, client_details) => {
             return response.json();
         });
         client_id = client_registration["client_id"];
-        // remember client_id
+    }
+    // remember client_id if not URL
+    try {
+        new URL(client_id);
+    }
+    catch {
         sessionStorage.setItem("client_id", client_id);
     }
     // RFC 7636 PKCE, remember code verifer
@@ -2851,7 +2702,7 @@ const getPKCEcode = async () => {
  * URL contains authrization code, issuer (idp) and state (csrf token),
  * get an access token for the authrization code.
  */
-const onIncomingRedirect = async (client_details) => {
+const onIncomingRedirect = async (client_details, database) => {
     const url = new URL(window.location.href);
     // authorization code
     const authorization_code = url.searchParams.get("code");
@@ -2861,12 +2712,12 @@ const onIncomingRedirect = async (client_details) => {
     }
     // RFC 9207 issuer check
     const idp = sessionStorage.getItem("idp");
-    if (idp === null || url.searchParams.get("iss") != idp) {
-        throw new Error("RFC 9207 - iss != idp - " + url.searchParams.get("iss") + " != " + idp);
+    if (idp === null || url.searchParams.get("iss") !== idp) {
+        throw new Error("RFC 9207 - iss !== idp - " + url.searchParams.get("iss") + " !== " + idp);
     }
     // RFC 6749 OAuth 2.0
-    if (url.searchParams.get("state") != sessionStorage.getItem("csrf_token")) {
-        throw new Error("RFC 6749 - state != csrf_token - " + url.searchParams.get("state") + " != " + sessionStorage.getItem("csrf_token"));
+    if (url.searchParams.get("state") !== sessionStorage.getItem("csrf_token")) {
+        throw new Error("RFC 6749 - state !== csrf_token - " + url.searchParams.get("state") + " !== " + sessionStorage.getItem("csrf_token"));
     }
     // remove redirect query parameters from URL
     url.searchParams.delete("iss");
@@ -2910,30 +2761,32 @@ const onIncomingRedirect = async (client_details) => {
     });
     // check dpop thumbprint
     const dpopThumbprint = await calculateJwkThumbprint(await exportJWK(key_pair.publicKey));
-    if (payload["cnf"]["jkt"] != dpopThumbprint) {
-        throw new Error("Access Token validation failed on `jkt`: jkt != DPoP thumbprint - " + payload["cnf"]["jkt"] + " != " + dpopThumbprint);
+    if (payload["cnf"]["jkt"] !== dpopThumbprint) {
+        throw new Error("Access Token validation failed on `jkt`: jkt !== DPoP thumbprint - " + payload["cnf"]["jkt"] + " !== " + dpopThumbprint);
     }
     // check client_id
-    if (payload["client_id"] != client_id) {
-        throw new Error("Access Token validation failed on `client_id`: JWT payload != client_id - " + payload["client_id"] + " != " + client_id);
+    if (payload["client_id"] !== client_id) {
+        throw new Error("Access Token validation failed on `client_id`: JWT payload !== client_id - " + payload["client_id"] + " !== " + client_id);
     }
     // summarise session info
     const token_details = { ...token_response, dpop_key_pair: key_pair };
     const idp_details = { idp, jwks_uri, token_endpoint };
     if (!client_details)
-        client_details = { redirect_uris: [window.location.href] };
+        client_details = { redirect_uris: [url.toString()] };
     client_details.client_id = client_id;
-    // to remember for session restore
-    const sessionDatabase = await new SessionDatabase().init();
-    await Promise.all([
-        sessionDatabase.setItem("idp", idp),
-        sessionDatabase.setItem("jwks_uri", jwks_uri),
-        sessionDatabase.setItem("token_endpoint", token_endpoint),
-        sessionDatabase.setItem("client_id", client_id),
-        sessionDatabase.setItem("dpop_keypair", key_pair),
-        sessionDatabase.setItem("refresh_token", token_response["refresh_token"])
-    ]);
-    sessionDatabase.close();
+    // and persist refresh token details
+    if (database) {
+        await database.init();
+        await Promise.all([
+            database.setItem("idp", idp),
+            database.setItem("jwks_uri", jwks_uri),
+            database.setItem("token_endpoint", token_endpoint),
+            database.setItem("client_id", client_id),
+            database.setItem("dpop_keypair", key_pair),
+            database.setItem("refresh_token", token_response["refresh_token"])
+        ]);
+        database.close();
+    }
     // clean session storage
     sessionStorage.removeItem("csrf_token");
     sessionStorage.removeItem("pkce_code_verifier");
@@ -2991,56 +2844,60 @@ const requestAccessToken = async (authorization_code, pkce_code_verifier, redire
     });
 };
 
-const renewTokens = async () => {
+const renewTokens = async (sessionDatabase) => {
     // remember session details
-    const sessionDatabase = await new SessionDatabase().init();
-    const client_id = await sessionDatabase.getItem("client_id");
-    const token_endpoint = await sessionDatabase.getItem("token_endpoint");
-    const key_pair = await sessionDatabase.getItem("dpop_keypair");
-    const refresh_token = await sessionDatabase.getItem("refresh_token");
-    if (client_id === null || token_endpoint === null || key_pair === null || refresh_token === null) {
-        // we can not restore the old session
-        throw new Error("Could not refresh tokens: details missing from database.");
-    }
-    const token_response = await requestFreshTokens(refresh_token, client_id, token_endpoint, key_pair)
-        .then((response) => {
-        if (!response.ok) {
-            throw new Error(`HTTP error! Status: ${response.status}`);
+    try {
+        await sessionDatabase.init();
+        const client_id = await sessionDatabase.getItem("client_id");
+        const token_endpoint = await sessionDatabase.getItem("token_endpoint");
+        const key_pair = await sessionDatabase.getItem("dpop_keypair");
+        const refresh_token = await sessionDatabase.getItem("refresh_token");
+        if (client_id === null || token_endpoint === null || key_pair === null || refresh_token === null) {
+            // we can not restore the old session
+            throw new Error("Could not refresh tokens: details missing from database.");
+        }
+        const token_response = await requestFreshTokens(refresh_token, client_id, token_endpoint, key_pair)
+            .then((response) => {
+            if (!response.ok) {
+                throw new Error(`HTTP error! Status: ${response.status}`);
+            }
+            return response.json();
+        });
+        // verify access_token // ! Solid-OIDC specification says it should be a dpop-bound `id token` but implementations provide a dpop-bound `access token`
+        const accessToken = token_response["access_token"];
+        const idp = await sessionDatabase.getItem("idp");
+        if (idp === null) {
+            throw new Error("Access Token validation preparation - Could not find in sessionDatabase: idp");
+        }
+        const jwks_uri = await sessionDatabase.getItem("jwks_uri");
+        if (jwks_uri === null) {
+            throw new Error("Access Token validation preparation - Could not find in sessionDatabase: jwks_uri");
+        }
+        const jwks = createRemoteJWKSet(new URL(jwks_uri));
+        const { payload } = await jwtVerify(accessToken, jwks, {
+            issuer: idp, // RFC 9207
+            audience: "solid", // RFC 7519 // ! "solid" as per implementations ...
+            // exp, nbf, iat - handled automatically
+        });
+        // check dpop thumbprint
+        const dpopThumbprint = await calculateJwkThumbprint(await exportJWK(key_pair.publicKey));
+        if (payload["cnf"]["jkt"] !== dpopThumbprint) {
+            throw new Error("Access Token validation failed on `jkt`: jkt !== DPoP thumbprint - " + payload["cnf"]["jkt"] + " !== " + dpopThumbprint);
         }
-        return response.json();
-    });
-    // verify access_token // ! Solid-OIDC specification says it should be a dpop-bound `id token` but implementations provide a dpop-bound `access token`
-    const accessToken = token_response["access_token"];
-    const idp = await sessionDatabase.getItem("idp");
-    if (idp === null) {
-        throw new Error("Access Token validation preparation - Could not find in sessionDatabase: idp");
-    }
-    const jwks_uri = await sessionDatabase.getItem("jwks_uri");
-    if (jwks_uri === null) {
-        throw new Error("Access Token validation preparation - Could not find in sessionDatabase: jwks_uri");
-    }
-    const jwks = createRemoteJWKSet(new URL(jwks_uri));
-    const { payload } = await jwtVerify(accessToken, jwks, {
-        issuer: idp, // RFC 9207
-        audience: "solid", // RFC 7519 // ! "solid" as per implementations ...
-        // exp, nbf, iat - handled automatically
-    });
-    // check dpop thumbprint
-    const dpopThumbprint = await calculateJwkThumbprint(await exportJWK(key_pair.publicKey));
-    if (payload["cnf"]["jkt"] != dpopThumbprint) {
-        throw new Error("Access Token validation failed on `jkt`: jkt != DPoP thumbprint - " + payload["cnf"]["jkt"] + " != " + dpopThumbprint);
+        // check client_id
+        if (payload["client_id"] !== client_id) {
+            throw new Error("Access Token validation failed on `client_id`: JWT payload !== client_id - " + payload["client_id"] + " !== " + client_id);
+        }
+        // set new refresh token for token rotation
+        await sessionDatabase.setItem("refresh_token", token_response["refresh_token"]);
+        return {
+            ...token_response,
+            dpop_key_pair: key_pair,
+        };
     }
-    // check client_id
-    if (payload["client_id"] != client_id) {
-        throw new Error("Access Token validation failed on `client_id`: JWT payload != client_id - " + payload["client_id"] + " != " + client_id);
+    finally {
+        sessionDatabase.close();
     }
-    // set new refresh token for token rotation
-    await sessionDatabase.setItem("refresh_token", token_response["refresh_token"]);
-    sessionDatabase.close();
-    return {
-        ...token_response,
-        dpop_key_pair: key_pair,
-    };
 };
 /**
  * Request an dpop-bound access token from a token endpoint using a refresh token
@@ -3062,7 +2919,7 @@ const requestFreshTokens = async (refresh_token, client_id, token_endpoint, key_
         htm: "POST",
     })
         .setIssuedAt()
-        .setJti(window.crypto.randomUUID())
+        .setJti(self.crypto.randomUUID())
         .setProtectedHeader({
         alg: "ES256",
         typ: "dpop+jwt",
@@ -3083,113 +2940,118 @@ const requestFreshTokens = async (refresh_token, client_id, token_endpoint, key_
     });
 };
 
-class Session {
-    sessionInformation;
+//
+//
+//  Basic implementation
+//
+//
+/**
+ * The SessionCore class manages session state and core logic but does not handle the refresh lifecycle.
+ * It receives {@link SessionOptions} with a database to be able to restore a session.
+ * That database can be re-used by (your!) surrounding implementation to handle the refresh lifecycle.
+ * If no database was provided, refresh information cannot be stored, and thus token refresh (via the refresh token grant) is not possible in this case.
+ *
+ * If you are building a web app, use the Session implementation provided in the default `/web` version of this library.
+ */
+class SessionCore {
     isActive_ = false;
+    exp_;
     webId_ = undefined;
     currentAth_ = undefined;
-    tokenRefreshTimeout;
-    sessionDeactivateTimeout;
-    onSessionExpirationWarning;
-    /**
-     * Create a new session.
-     */
+    onSessionStateChange;
+    information;
+    database;
+    refreshPromise;
+    resolveRefresh;
+    rejectRefresh;
     constructor(clientDetails, sessionOptions) {
-        this.sessionInformation = { clientDetails };
-        this.onSessionExpirationWarning = sessionOptions?.onSessionExpirationWarning;
+        this.information = { clientDetails };
+        this.database = sessionOptions?.database;
+        this.onSessionStateChange = sessionOptions?.onSessionStateChange;
     }
-    /**
-     * Redirect the user for login to their IDP.
-     *
-     * @throws Error if the session has not been initialized.
-     */
     async login(idp, redirect_uri) {
-        await redirectForLogin(idp, redirect_uri, this.sessionInformation.clientDetails);
-    }
-    /**
-     * Clears all session-related information, including IDP details and tokens.
-     * This logs the user out.
-     * Client details are preserved.
-     */
-    async logout() {
-        // clear timeouts
-        if (this.sessionDeactivateTimeout)
-            clearTimeout(this.sessionDeactivateTimeout);
-        this.sessionDeactivateTimeout = undefined;
-        if (this.tokenRefreshTimeout)
-            clearTimeout(this.tokenRefreshTimeout);
-        this.tokenRefreshTimeout = undefined;
-        // clean session data
-        this.sessionInformation.idpDetails = undefined;
-        this.sessionInformation.tokenDetails = undefined;
-        this.isActive_ = false;
-        this.webId_ = undefined;
-        // only preserve client_id if URI
-        if (this.sessionInformation.clientDetails?.client_id)
-            try {
-                new URL(this.sessionInformation.clientDetails.client_id);
-            }
-            catch (_) {
-                this.sessionInformation.clientDetails.client_id = undefined;
-            }
-        // clean session database
-        const sessionDatabase = await new SessionDatabase().init();
-        await sessionDatabase.clear();
-        sessionDatabase.close();
+        await redirectForLogin(idp, redirect_uri, this.information.clientDetails);
     }
     /**
      * Handles the redirect from the identity provider after a login attempt.
      * It attempts to retrieve tokens using the authorization code.
+     * Upon success, it tries to persist information to refresh tokens in the session database.
+     * If no database was provided, no information is persisted.
      */
     async handleRedirectFromLogin() {
         // Redirect after Authorization Code Grant // memory via sessionStorage
-        const newSessionInfo = await onIncomingRedirect(this.sessionInformation.clientDetails);
+        const newSessionInfo = await onIncomingRedirect(this.information.clientDetails, this.database);
         // no session - we remain unauthenticated
-        if (!newSessionInfo.tokenDetails) {
+        if (!newSessionInfo.tokenDetails)
             return;
-        }
         // we got a session
-        this.sessionInformation = newSessionInfo;
-        await this.setSessionDetails();
+        this.information.clientDetails = newSessionInfo.clientDetails;
+        this.information.idpDetails = newSessionInfo.idpDetails;
+        await this.setTokenDetails(newSessionInfo.tokenDetails);
+        // callback state change 
+        this.onSessionStateChange?.(); // we logged in
     }
     /**
      * Handles session restoration using the refresh token grant.
      * Silently fails if session could not be restored (maybe there was no session in the first place).
      */
     async restore() {
-        // Restore session using Refresh Token Grant // memory via IndexedDB
-        await renewTokens()
-            .then(tokenDetails => {
-            // got new tokens
-            this.sessionInformation.tokenDetails = tokenDetails;
-            // set session information
-            return this.setSessionDetails();
-        })
-            // anything missing or wrong => abort, could not restore session.
-            .catch(_ => { }); // fail silently
+        if (!this.database) {
+            throw new Error("Could not refresh tokens: missing database. Provide database in sessionOption.");
+        }
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = new Promise((resolve, reject) => {
+            this.resolveRefresh = resolve;
+            this.rejectRefresh = reject;
+        });
+        // Restore session using Refresh Token Grant 
+        const wasActive = this.isActive;
+        renewTokens(this.database)
+            .then(tokenDetails => this.setTokenDetails(tokenDetails))
+            .then(() => this.resolveRefresh())
+            .catch(error => {
+            if (this.isActive) {
+                this.rejectRefresh(new Error(error || 'Token refresh failed'));
+                // do not change state (yet), let the app decide if they want to logout or if they just want to retry.
+            }
+            else {
+                this.rejectRefresh(new Error("No session to restore."));
+            }
+        }).finally(() => {
+            this.clearRefreshPromise();
+            if (wasActive !== this.isActive)
+                this.onSessionStateChange?.();
+        });
+        return this.refreshPromise;
     }
     /**
-     * Creates a signed DPoP (Demonstration of Proof-of-Possession) token.
-     *
-     * @param payload The payload to include in the DPoP token. By default, it includes `htu` (HTTP target URI) and `htm` (HTTP method).
-     * @returns A promise that resolves to the signed DPoP token string.
-     * @throws Error if the session has not been initialized - if no token details are available.
+     * This logs the user out.
+     * Clears all session-related information, including IDP details and tokens.
+     * Client ID is preserved if it is a URI.
      */
-    async createSignedDPoPToken(payload) {
-        if (!this.sessionInformation.tokenDetails || !this.currentAth_) {
-            throw new Error("Session not established.");
+    async logout() {
+        // clean session data
+        this.isActive_ = false;
+        this.exp_ = undefined;
+        this.webId_ = undefined;
+        this.currentAth_ = undefined;
+        this.information.idpDetails = undefined;
+        this.information.tokenDetails = undefined;
+        // client details are preserved
+        if (this.refreshPromise && this.rejectRefresh) {
+            this.rejectRefresh(new Error('Logout during token refresh.'));
+            this.clearRefreshPromise();
         }
-        payload.ath = this.currentAth_;
-        const jwk_public_key = await exportJWK(this.sessionInformation.tokenDetails.dpop_key_pair.publicKey);
-        return new SignJWT(payload)
-            .setIssuedAt()
-            .setJti(window.crypto.randomUUID())
-            .setProtectedHeader({
-            alg: "ES256",
-            typ: "dpop+jwt",
-            jwk: jwk_public_key,
-        })
-            .sign(this.sessionInformation.tokenDetails.dpop_key_pair.privateKey);
+        // clean session database
+        if (this.database) {
+            await this.database.init();
+            await this.database.clear();
+            this.database.close();
+        }
+        // callback state change
+        this.onSessionStateChange?.(); // we logged out
     }
     /**
      * Makes an HTTP fetch request.
@@ -3201,10 +3063,18 @@ class Session {
      * @returns A promise that resolves to the fetch Response.
      */
     async authFetch(input, init, dpopPayload) {
+        // if there is not session established, just delegate to the default fetch
+        if (!this.isActive) {
+            return fetch(input, init);
+        }
+        // TODO
+        // TODO do HEAD request to check if authentication is actually required, only then include tokens
+        // TODO
         // prepare authenticated call using a DPoP token (either provided payload, or default)
         let url;
         let method;
         let headers;
+        // wrangle fetch input parameters into place
         if (input instanceof Request) {
             url = new URL(input.url);
             method = init?.method || input?.method || 'GET';
@@ -3217,15 +3087,15 @@ class Session {
             headers = init.headers ? new Headers(init.headers) : new Headers();
         }
         // create DPoP token, and add tokens to request
-        if (this.sessionInformation.tokenDetails) {
-            dpopPayload = dpopPayload ?? {
-                htu: `${url.origin}${url.pathname}`,
-                htm: method.toUpperCase()
-            };
-            const dpop = await this.createSignedDPoPToken(dpopPayload);
-            headers.set("dpop", dpop);
-            headers.set("authorization", `DPoP ${this.sessionInformation.tokenDetails.access_token}`);
-        }
+        await this._renewTokensIfExpired();
+        dpopPayload = dpopPayload ?? {
+            htu: `${url.origin}${url.pathname}`,
+            htm: method.toUpperCase()
+        };
+        const dpop = await this._createSignedDPoPToken(dpopPayload);
+        // overwrite headers: authorization, dpop
+        headers.set("dpop", dpop);
+        headers.set("authorization", `DPoP ${this.information.tokenDetails.access_token}`);
         // check explicitly; to avoid unexpected behaviour
         if (input instanceof Request) { // clone the provided request, and override the headers
             return fetch(new Request(input, { ...init, headers }));
@@ -3233,64 +3103,59 @@ class Session {
         // just override the headers
         return fetch(url, { ...init, headers });
     }
+    // 
+    // Setters
+    //
+    async setTokenDetails(tokenDetails) {
+        this.information.tokenDetails = tokenDetails;
+        await this._updateSessionDetailsFromToken(tokenDetails.access_token);
+    }
+    clearRefreshPromise() {
+        this.refreshPromise = undefined;
+        this.resolveRefresh = undefined;
+        this.rejectRefresh = undefined;
+    }
+    //
+    // Getters
+    //
     get isActive() {
         return this.isActive_;
     }
     get webId() {
         return this.webId_;
     }
+    getExpiresIn() {
+        return this.information.tokenDetails?.expires_in ?? -1;
+    }
+    isExpired() {
+        if (!this.exp_)
+            return true;
+        return this._isTokenExpired(this.exp_);
+    }
+    getTokenDetails() {
+        return this.information.tokenDetails;
+    }
     //
-    // Helper Methods
+    // Helpers
     //
     /**
-     * Set the session to active if there is an access token.
+     * Check if the current token is expired (which may happen during device/browser/tab hibernation),
+     * and if expired, restore the session.
      */
-    async setSessionDetails() {
-        // check for access token 
-        if (!this.sessionInformation.tokenDetails?.access_token) {
-            this.logout();
-        }
-        // generate ath
-        this.currentAth_ = await this.computeAth(this.sessionInformation.tokenDetails.access_token);
-        // check for active session
-        this.webId_ = decodeJwt(this.sessionInformation.tokenDetails.access_token)["webid"];
-        this.isActive_ = this.webId !== undefined;
-        // deactivating session when token expire
-        this.setSessionDeactivateTimeout();
-        // refreshing tokens
-        this.setTokenRefreshTimeout();
-    }
-    setSessionDeactivateTimeout() {
-        const deactivate_buffer_seconds = 5;
-        const timeUntilDeactivate = (this.sessionInformation.tokenDetails.expires_in - deactivate_buffer_seconds) * 1000;
-        if (this.sessionDeactivateTimeout)
-            clearTimeout(this.sessionDeactivateTimeout);
-        this.sessionDeactivateTimeout = setTimeout(() => this.logout(), timeUntilDeactivate);
-    }
-    setTokenRefreshTimeout() {
-        const refresh_buffer_seconds = 95;
-        const timeUntilRefresh = (this.sessionInformation.tokenDetails.expires_in - refresh_buffer_seconds) * 1000;
-        if (this.tokenRefreshTimeout)
-            clearTimeout(this.tokenRefreshTimeout);
-        this.tokenRefreshTimeout = setTimeout(async () => {
-            const newTokens = await renewTokens()
-                .catch((error) => {
-                // anything missing or wrong => could not renew tokens.
-                if (this.onSessionExpirationWarning)
-                    this.onSessionExpirationWarning();
-                return undefined;
-            });
-            if (!newTokens) {
-                return;
+    async _renewTokensIfExpired() {
+        if (this.isExpired()) {
+            if (!this.refreshPromise) {
+                await this.restore(); // Initiate and wait
+            }
+            else {
+                await this.refreshPromise; // Wait for already pending
             }
-            this.sessionInformation.tokenDetails = newTokens;
-            this.setSessionDetails();
-        }, timeUntilRefresh);
+        }
     }
     /**
      * RFC 9449 - Hash of the access token
      */
-    async computeAth(accessToken) {
+    async _computeAth(accessToken) {
         // Convert the ASCII string of the token to a Uint8Array
         const encoder = new TextEncoder();
         const data = encoder.encode(accessToken); // ASCII by default
@@ -3306,6 +3171,470 @@ class Session {
             .replace(/=+$/, '');
         return base64url;
     }
+    /**
+     * Creates a signed DPoP (Demonstration of Proof-of-Possession) token.
+     *
+     * @param payload The payload to include in the DPoP token. By default, it includes `htu` (HTTP target URI) and `htm` (HTTP method).
+     * @returns A promise that resolves to the signed DPoP token string.
+     * @throws Error if the session has not been initialized - if no token details are available.
+     */
+    async _createSignedDPoPToken(payload) {
+        if (!this.information.tokenDetails || !this.currentAth_) {
+            throw new Error("Session not established.");
+        }
+        payload.ath = this.currentAth_;
+        const jwk_public_key = await exportJWK(this.information.tokenDetails.dpop_key_pair.publicKey);
+        return new SignJWT(payload)
+            .setIssuedAt()
+            .setJti(window.crypto.randomUUID())
+            .setProtectedHeader({
+            alg: "ES256",
+            typ: "dpop+jwt",
+            jwk: jwk_public_key,
+        })
+            .sign(this.information.tokenDetails.dpop_key_pair.privateKey);
+    }
+    async _updateSessionDetailsFromToken(access_token) {
+        if (!access_token) {
+            await this.logout();
+            return;
+        }
+        try {
+            const decodedToken = decodeJwt(access_token);
+            const webId = decodedToken.webid;
+            if (!webId) {
+                throw new Error('Missing webid claim in access token');
+            }
+            const exp = decodedToken.exp;
+            if (!exp) {
+                throw new Error('Missing exp claim in access token');
+            }
+            this.currentAth_ = await this._computeAth(access_token); // must be done before session set to active
+            this.webId_ = webId;
+            this.exp_ = exp;
+            this.isActive_ = true;
+        }
+        catch (error) {
+            await this.logout();
+        }
+    }
+    /**
+      * Checks if a JWT expiration timestamp ('exp') has passed.
+      */
+    _isTokenExpired(exp, bufferSeconds = 0) {
+        if (typeof exp !== 'number' || isNaN(exp)) {
+            return true;
+        }
+        const currentTimeSeconds = Math.floor(Date.now() / 1000);
+        return exp < (currentTimeSeconds + bufferSeconds);
+    }
+}
+
+// extracting this from Session.ts such that the jest tests would compile :)
+const getWorkerUrl = () => new URL('./RefreshWorker.js', (typeof document === 'undefined' ? new (require('u' + 'rl').URL)('file:' + __filename).href : (document.currentScript && document.currentScript.src || new URL('ion-icon.ion-progress-bar.ion-skeleton-text.pos-add-new-thing.pos-app.pos-app-browser.pos-app-dashboard.pos-app-settings.pos-description.pos-dialog.pos-error-toast.pos-example-resources.pos-getting-started.pos-image.pos-internal-router.pos-label.pos-login.pos-login-form.pos-make-findable.pos-navigation.pos-navigation-bar.pos-new-thing-form.pos-picture.pos-resource.pos-rich-link.pos-router.pos-select-term.pos-setting-offline-cache.pos-tool-select.pos-type-router.pos-user-menu.entry.cjs.js', document.baseURI).href)));
+
+/**
+ * A simple IndexedDB wrapper.
+ */
+class SessionIDB {
+    dbName;
+    storeName;
+    dbVersion;
+    db = null;
+    /**
+     * Creates a new instance
+     * @param dbName The name of the IndexedDB database
+     * @param storeName The name of the object store
+     * @param dbVersion The database version
+     */
+    constructor(dbName = 'soidc', storeName = 'session', dbVersion = 1) {
+        this.dbName = dbName;
+        this.storeName = storeName;
+        this.dbVersion = dbVersion;
+    }
+    /**
+     * Initializes the IndexedDB database
+     * @returns Promise that resolves when the database is ready
+     */
+    async init() {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(this.dbName, this.dbVersion);
+            request.onerror = (event) => {
+                reject(new Error(`Database error: ${event.target.error}`));
+            };
+            request.onsuccess = (event) => {
+                this.db = event.target.result;
+                resolve(this);
+            };
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                // Check if the object store already exists, if not create it
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    db.createObjectStore(this.storeName);
+                }
+            };
+        });
+    }
+    /**
+     * Stores any value in the database with the given ID as key
+     * @param id The identifier/key for the value
+     * @param value The value to store
+     */
+    async setItem(id, value) {
+        if (!this.db) {
+            await this.init();
+        }
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(this.storeName, 'readwrite');
+            // Handle transation
+            transaction.oncomplete = () => {
+                resolve();
+            };
+            transaction.onerror = (event) => {
+                reject(new Error(`Transaction error for setItem(${id},...): ${event.target.error}`));
+            };
+            transaction.onabort = (event) => {
+                reject(new Error(`Transaction aborted for setItem(${id},...): ${event.target.error}`));
+            };
+            // Perform the request within the transaction
+            const store = transaction.objectStore(this.storeName);
+            store.put(value, id);
+        });
+    }
+    /**
+      * Retrieves a value from the database by ID
+      * @param id The identifier/key for the value
+      * @returns The stored value or null if not found
+      */
+    async getItem(id) {
+        if (!this.db) {
+            await this.init();
+        }
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(this.storeName, 'readonly');
+            // Handle transation
+            transaction.onerror = (event) => {
+                reject(new Error(`Transaction error for getItem(${id}): ${event.target.error}`));
+            };
+            transaction.onabort = (event) => {
+                reject(new Error(`Transaction aborted for getItem(${id}): ${event.target.error}`));
+            };
+            // Perform the request within the transaction
+            const store = transaction.objectStore(this.storeName);
+            const request = store.get(id);
+            request.onsuccess = () => {
+                resolve(request.result || null);
+            };
+        });
+    }
+    /**
+     * Removes an item from the database
+     * @param id The identifier of the item to remove
+     */
+    async deleteItem(id) {
+        if (!this.db) {
+            await this.init();
+        }
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(this.storeName, 'readwrite');
+            // Handle transation
+            transaction.oncomplete = () => {
+                resolve();
+            };
+            transaction.onerror = (event) => {
+                reject(new Error(`Transaction error for deleteItem(${id}): ${event.target.error}`));
+            };
+            transaction.onabort = (event) => {
+                reject(new Error(`Transaction aborted for deleteItem(${id}): ${event.target.error}`));
+            };
+            // Perform the request within the transaction
+            const store = transaction.objectStore(this.storeName);
+            store.delete(id);
+        });
+    }
+    /**
+     * Clears all items from the database
+     */
+    async clear() {
+        if (!this.db) {
+            await this.init();
+        }
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(this.storeName, 'readwrite');
+            // Handle transation
+            transaction.oncomplete = () => {
+                resolve();
+            };
+            transaction.onerror = (event) => {
+                reject(new Error(`Transaction error for clear(): ${event.target.error}`));
+            };
+            transaction.onabort = (event) => {
+                reject(new Error(`Transaction aborted for clear(): ${event.target.error}`));
+            };
+            // Perform the request within the transaction
+            const store = transaction.objectStore(this.storeName);
+            store.clear();
+        });
+    }
+    /**
+     * Closes the database connection
+     */
+    close() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+    }
+}
+
+var RefreshMessageTypes;
+(function (RefreshMessageTypes) {
+    RefreshMessageTypes["SCHEDULE"] = "SCHEDULE";
+    RefreshMessageTypes["REFRESH"] = "REFRESH";
+    RefreshMessageTypes["STOP"] = "STOP";
+    RefreshMessageTypes["DISCONNECT"] = "DISCONNECT";
+    RefreshMessageTypes["TOKEN_DETAILS"] = "TOKEN_DETAILS";
+    RefreshMessageTypes["ERROR_ON_REFRESH"] = "ERROR_ON_REFRESH";
+    RefreshMessageTypes["EXPIRED"] = "EXPIRED";
+})(RefreshMessageTypes || (RefreshMessageTypes = {}));
+// A Set to store all connected ports (tabs)
+const ports = new Set();
+const broadcast = (message) => {
+    for (const p of ports) {
+        p.postMessage(message);
+    }
+};
+let refresher;
+self.onconnect = (event) => {
+    const port = event.ports[0];
+    ports.add(port);
+    // lazy init
+    if (!refresher) {
+        refresher = new Refresher(broadcast, new SessionIDB());
+    }
+    // handle messages
+    port.onmessage = (event) => {
+        const { type, payload } = event.data;
+        switch (type) {
+            case RefreshMessageTypes.SCHEDULE:
+                refresher.handleSchedule(payload);
+                break;
+            case RefreshMessageTypes.REFRESH:
+                refresher.handleRefresh(port);
+                break;
+            case RefreshMessageTypes.STOP:
+                refresher.handleStop();
+                break;
+            case RefreshMessageTypes.DISCONNECT:
+                ports.delete(port);
+                break;
+        }
+    };
+    port.onmessageerror = () => ports.delete(port);
+    port.start();
+};
+class Refresher {
+    tokenDetails;
+    exp;
+    refreshTimeout;
+    finalLogoutTimeout;
+    timersAreRunning = false;
+    broadcast;
+    database;
+    refreshPromise;
+    constructor(broadcast, database) {
+        this.broadcast = broadcast;
+        this.database = database;
+    }
+    async handleSchedule(tokenDetails) {
+        this.tokenDetails = tokenDetails;
+        this.exp = decodeJwt(this.tokenDetails.access_token).exp;
+        this.broadcast({
+            type: RefreshMessageTypes.TOKEN_DETAILS,
+            payload: { tokenDetails: this.tokenDetails }
+        });
+        console.log(`[RefreshWorker] Scheduling timers, expiry in ${this.tokenDetails.expires_in}s`);
+        this.scheduleTimers(this.tokenDetails.expires_in);
+        this.timersAreRunning = true;
+    }
+    async handleRefresh(requestingPort) {
+        if (this.tokenDetails && this.exp && !this.isTokenExpired(this.exp)) {
+            console.log(`[RefreshWorker] Providing current tokens`);
+            requestingPort.postMessage({
+                type: RefreshMessageTypes.TOKEN_DETAILS,
+                payload: { tokenDetails: this.tokenDetails }
+            });
+        }
+        else {
+            console.log(`[RefreshWorker] Refreshing tokens`);
+            this.performRefresh();
+        }
+    }
+    handleStop() {
+        if (!this.tokenDetails) {
+            console.log('[RefreshWorker] Received STOP, being idle');
+            return;
+        }
+        this.broadcast({ type: RefreshMessageTypes.EXPIRED });
+        this.tokenDetails = undefined;
+        this.exp = undefined;
+        this.refreshPromise = undefined;
+        console.log('[RefreshWorker] Received STOP, clearing timers');
+        this.clearAllTimers();
+    }
+    async performRefresh() {
+        if (this.refreshPromise) {
+            console.log('[RefreshWorker] Refresh already in progress, waiting...');
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.doRefresh();
+        return this.refreshPromise;
+    }
+    async doRefresh() {
+        try {
+            this.tokenDetails = await renewTokens(this.database);
+            this.exp = decodeJwt(this.tokenDetails.access_token).exp;
+            this.broadcast({
+                type: RefreshMessageTypes.TOKEN_DETAILS,
+                payload: { tokenDetails: this.tokenDetails }
+            });
+            console.log(`[RefreshWorker] Token refreshed`);
+            console.log(`[RefreshWorker] Scheduling timers, expiry in ${this.tokenDetails.expires_in}s`);
+            this.scheduleTimers(this.tokenDetails.expires_in);
+        }
+        catch (error) {
+            this.broadcast({
+                type: RefreshMessageTypes.ERROR_ON_REFRESH,
+                error: error.message
+            });
+            console.log(`[RefreshWorker]`, error.message);
+        }
+        finally {
+            this.refreshPromise = undefined;
+        }
+    }
+    clearAllTimers() {
+        if (this.refreshTimeout)
+            clearTimeout(this.refreshTimeout);
+        if (this.finalLogoutTimeout)
+            clearTimeout(this.finalLogoutTimeout);
+        this.timersAreRunning = false;
+    }
+    scheduleTimers(expiresIn) {
+        this.clearAllTimers();
+        this.timersAreRunning = true;
+        const expiresInMs = expiresIn * 1000;
+        const REFRESH_THRESHOLD_RATIO = 0.8;
+        const MINIMUM_REFRESH_BUFFER_MS = 30 * 1000;
+        const timeUntilRefresh = REFRESH_THRESHOLD_RATIO * expiresInMs;
+        if (timeUntilRefresh > MINIMUM_REFRESH_BUFFER_MS) {
+            this.refreshTimeout = setTimeout(() => this.performRefresh(), timeUntilRefresh);
+        }
+        const LOGOUT_WARNING_BUFFER_MS = 5 * 1000;
+        const timeUntilLogout = expiresInMs - LOGOUT_WARNING_BUFFER_MS;
+        this.finalLogoutTimeout = setTimeout(() => {
+            this.tokenDetails = undefined;
+            this.broadcast({ type: RefreshMessageTypes.EXPIRED });
+        }, timeUntilLogout);
+    }
+    isTokenExpired(exp, bufferSeconds = 0) {
+        if (typeof exp !== 'number' || isNaN(exp)) {
+            return true;
+        }
+        const currentTimeSeconds = Math.floor(Date.now() / 1000);
+        return exp < (currentTimeSeconds + bufferSeconds);
+    }
+    setTokenDetails(tokenDetails) {
+        this.tokenDetails = tokenDetails;
+    }
+    // For testing
+    getTimersAreRunning() { return this.timersAreRunning; }
+    getTokenDetails() { return this.tokenDetails; }
+}
+
+/**
+ * This Session provides background token refreshing using a Web Worker.
+ */
+class WebWorkerSession extends SessionCore {
+    worker;
+    onSessionExpirationWarning;
+    onSessionExpiration;
+    constructor(clientDetails, sessionOptions) {
+        const database = new SessionIDB();
+        const options = { ...sessionOptions, database };
+        super(clientDetails, options);
+        this.onSessionExpirationWarning = sessionOptions?.onSessionExpirationWarning;
+        this.onSessionExpiration = sessionOptions?.onSessionExpiration;
+        // Allow consumer to provide worker URL, or use default
+        const workerUrl = sessionOptions?.workerUrl ?? getWorkerUrl();
+        this.worker = new SharedWorker(workerUrl, { type: 'module' });
+        this.worker.port.onmessage = (event) => {
+            this.handleWorkerMessage(event.data).catch(console.error);
+        };
+        window.addEventListener('beforeunload', () => {
+            this.worker.port.postMessage({ type: RefreshMessageTypes.DISCONNECT });
+        });
+    }
+    async handleWorkerMessage(data) {
+        const { type, payload, error } = data;
+        switch (type) {
+            case RefreshMessageTypes.TOKEN_DETAILS:
+                const wasActive = this.isActive;
+                await this.setTokenDetails(payload.tokenDetails);
+                if (wasActive !== this.isActive)
+                    this.onSessionStateChange?.();
+                if (this.refreshPromise && this.resolveRefresh) {
+                    this.resolveRefresh();
+                    this.clearRefreshPromise();
+                }
+                break;
+            case RefreshMessageTypes.ERROR_ON_REFRESH:
+                if (this.isActive)
+                    this.onSessionExpirationWarning?.();
+                if (this.refreshPromise && this.rejectRefresh) {
+                    if (this.isActive) {
+                        this.rejectRefresh(new Error(error || 'Token refresh failed'));
+                    }
+                    else {
+                        this.rejectRefresh(new Error("No session to restore"));
+                    }
+                    this.clearRefreshPromise();
+                }
+                break;
+            case RefreshMessageTypes.EXPIRED:
+                if (this.isActive) {
+                    this.onSessionExpiration?.();
+                    await this.logout();
+                }
+                if (this.refreshPromise && this.rejectRefresh) {
+                    this.rejectRefresh(new Error(error || 'Token refresh failed'));
+                    this.clearRefreshPromise();
+                }
+                break;
+        }
+    }
+    ;
+    async handleRedirectFromLogin() {
+        await super.handleRedirectFromLogin();
+        if (this.isActive) { // If login was successful, tell the worker to schedule refreshing
+            this.worker.port.postMessage({ type: RefreshMessageTypes.SCHEDULE, payload: this.getTokenDetails() });
+        }
+    }
+    async restore() {
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = new Promise((resolve, reject) => {
+            this.resolveRefresh = resolve;
+            this.rejectRefresh = reject;
+        });
+        this.worker.port.postMessage({ type: RefreshMessageTypes.REFRESH });
+        return this.refreshPromise;
+    }
+    async logout() {
+        this.worker.port.postMessage({ type: RefreshMessageTypes.STOP });
+        await super.logout();
+    }
 }
 
 class BrowserSession {
@@ -3318,7 +3647,7 @@ class BrowserSession {
             isLoggedIn: false,
             webId: undefined,
         });
-        this.session = new Session();
+        this.session = new WebWorkerSession();
         this._authenticatedFetch = this.session.authFetch.bind(this.session);
     }
     async handleIncomingRedirect(restorePreviousSession = false) {