@geolonia/geonicdb-sdk 0.8.0 → 0.10.0

package/README.md

@@ -96,6 +96,77 @@ await db.login('user@example.com', 'password');
 // Token refresh is automatic via refresh token.
 ```
 
+#### DPoP-bound session (recommended for SPAs)
+
+If you persist tokens in storage that may be exposed to XSS
+(`localStorage` / `sessionStorage`), pass `{ dpop: true }` to immediately
+exchange the Bearer session for a **DPoP sender-constrained session**
+(RFC 9449). The SDK generates a non-extractable ECDSA P-256 key pair via Web
+Crypto and binds the access / refresh tokens to it, so a leaked token cannot
+be replayed from another origin.
+
+```typescript
+const result = await db.login('user@example.com', 'password', { dpop: true });
+// result.tokenType === 'DPoP'
+// Subsequent requests use `Authorization: DPoP <token>` + per-request proof.
+// Refresh calls send the DPoP proof on /auth/refresh as well.
+localStorage.setItem('accessToken', result.accessToken);
+localStorage.setItem('refreshToken', result.refreshToken);
+```
+
+Notes:
+
+- The bind step (`POST /auth/dpop-bind`) is performed transparently after
+  `POST /auth/login` succeeds.
+- The RFC 9449 §8 `use_dpop_nonce` handshake is handled internally.
+- Fails with `AuthenticationError` if Web Crypto `subtle.generateKey` is
+  unavailable, instead of silently falling back to Bearer (fail-closed).
+- Omitting the option preserves the previous behavior (Bearer only) for
+  backward compatibility.
+
+#### Persisting DPoP across page reloads
+
+By default, a DPoP session is held in memory only. Because the private key
+is generated as a **non-extractable** `CryptoKey`, it cannot be serialized
+to `localStorage` — and reloading the page would lose it, forcing the user
+to log in again.
+
+Pass `{ dpop: true, dpopPersist: true }` to persist the session to
+**IndexedDB**. The structured clone algorithm stores the `CryptoKey` as-is,
+preserving `extractable: false`: the key survives reloads, but JavaScript
+on the page still cannot read it back as JWK / PEM. Tokens leaked from any
+other storage remain unusable without this origin's IndexedDB.
+
+```typescript
+const db = new GeonicDB({ baseUrl, tenant });
+await db.login('user@example.com', 'password', {
+  dpop: true,
+  dpopPersist: true,
+});
+
+// On the next page load:
+const db2 = new GeonicDB({ baseUrl, tenant });
+if (await db2.restoreSession()) {
+  // Session was rehydrated from IndexedDB — boot the app.
+} else {
+  // No persisted session; show the login form.
+}
+
+// On logout, the persisted entry is cleared automatically.
+await db2.logout();
+```
+
+Notes:
+
+- `dpopPersist: true` requires `dpop: true` (throws otherwise). The
+  persistence mechanism is for DPoP key pairs specifically; persisting
+  Bearer tokens is the caller's responsibility.
+- The IndexedDB store is keyed by `tenant`, so multi-tenant apps in the
+  same origin keep separate sessions.
+- Persistence is best-effort: a failed IDB write does not break login.
+- iOS Safari may evict IndexedDB under ITP after 7 days of no user
+  interaction with the origin.
+
 ### External Token
 
 ```typescript
@@ -332,7 +403,8 @@ handle.stop();
 
 | Method | Parameters | Returns | Description |
 |--------|-----------|---------|-------------|
-| `login(email, password)` | `string, string` | `Promise<LoginResponse>` | Login with email and password (Bearer JWT). Upgrades the SDK out of anonymous mode |
+| `login(email, password, options?)` | `string, string, LoginOptions?` | `Promise<LoginResponse>` | Login with email and password (Bearer JWT). Upgrades the SDK out of anonymous mode. Pass `{ dpop: true }` to immediately exchange the Bearer session for a DPoP sender-constrained session (RFC 9449) — recommended when persisting tokens in storage exposed to XSS. Pass `{ dpop: true, dpopPersist: true }` to also persist the session to IndexedDB so it survives a page reload (#1230) |
+| `restoreSession()` | — | `Promise<boolean>` | Rehydrate a DPoP session previously persisted via `login({ dpop: true, dpopPersist: true })`. Returns `true` if a session was found and loaded, `false` otherwise. Call at app startup before showing the login form |
 | `setCredentials(opts)` | `CredentialsOptions` | `this` | Set credentials externally (e.g. from a login API response). Upgrades the SDK out of anonymous mode when `tokenType: 'Bearer'`. **Throws** when `tokenType: 'DPoP'` is passed to an anonymous-built instance — anonymous instances do not generate a DPoP key pair |
 | `logout()` | — | `void` | Clear all credentials and disconnect WebSocket. Reverts to anonymous mode if `anonymous: true` was set at construction |
 | `isAnonymous()` | — | `boolean` | Whether explicit anonymous mode is active. Returns the explicit mode flag — not derived from credential presence — so a refresh failure that clears `_token` does NOT silently flip this back to `true` |

package/geonicdb.cjs

@@ -72,8 +72,23 @@ var EventEmitter = class {
   }
 };
 
+// src/sdk/constants.ts
+var DEFAULT_TOKEN_TTL_SEC = 3600;
+var TOKEN_REFRESH_LEEWAY_MS = 12e4;
+var TOKEN_REFRESH_MIN_MS = 1e4;
+var RECONNECT_MAX_ATTEMPTS = 10;
+var RECONNECT_BASE_MS = 1e3;
+var RECONNECT_MAX_DELAY_MS = 3e4;
+var SUB_PROTOCOL = "access_token";
+var SDK_CACHE_MAX_ENTRIES_DEFAULT = 1e3;
+var SDK_POLL_INTERVAL_MS_DEFAULT = 5e3;
+var DPOP_IDB_NAME = "geonicdb-sdk";
+var DPOP_IDB_STORE = "dpop-sessions";
+var DPOP_IDB_VERSION = 1;
+
 // src/sdk/dpop.ts
 var dpopSupported = typeof crypto !== "undefined" && !!crypto.subtle && !!crypto.subtle.generateKey;
+var dpopPersistenceSupported = typeof globalThis.indexedDB !== "undefined" && typeof structuredClone !== "undefined";
 function b64url(buf) {
   const arr = buf instanceof ArrayBuffer ? new Uint8Array(buf) : buf;
   let str = "";
@@ -130,6 +145,102 @@ async function createDPoPProof(keyPair, htm, htu, accessToken, nonce) {
   );
   return signingInput + "." + b64url(new Uint8Array(sigBuf));
 }
+function openSessionDB() {
+  return new Promise((resolve, reject) => {
+    const req = globalThis.indexedDB.open(DPOP_IDB_NAME, DPOP_IDB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(DPOP_IDB_STORE)) {
+        db.createObjectStore(DPOP_IDB_STORE);
+      }
+    };
+    req.onsuccess = () => {
+      resolve(req.result);
+    };
+    req.onerror = () => {
+      reject(req.error ?? new Error("IndexedDB open failed"));
+    };
+  });
+}
+async function saveDPoPSession(session) {
+  if (!dpopPersistenceSupported) return false;
+  let db = null;
+  try {
+    db = await openSessionDB();
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(DPOP_IDB_STORE, "readwrite");
+      tx.objectStore(DPOP_IDB_STORE).put(session, session.tenant);
+      tx.oncomplete = () => {
+        resolve();
+      };
+      tx.onerror = () => {
+        reject(tx.error ?? new Error("IndexedDB put failed"));
+      };
+      tx.onabort = () => {
+        reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+      };
+    });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    db?.close();
+  }
+}
+async function loadDPoPSession(tenant) {
+  if (!dpopPersistenceSupported) return null;
+  let db = null;
+  try {
+    db = await openSessionDB();
+    const data = await new Promise((resolve, reject) => {
+      const tx = db.transaction(DPOP_IDB_STORE, "readonly");
+      const req = tx.objectStore(DPOP_IDB_STORE).get(tenant);
+      req.onsuccess = () => {
+        resolve(req.result);
+      };
+      req.onerror = () => {
+        reject(req.error ?? new Error("IndexedDB get failed"));
+      };
+    });
+    return validatePersistedSession(data);
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+async function clearDPoPSession(tenant) {
+  if (!dpopPersistenceSupported) return;
+  let db = null;
+  try {
+    db = await openSessionDB();
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(DPOP_IDB_STORE, "readwrite");
+      tx.objectStore(DPOP_IDB_STORE).delete(tenant);
+      tx.oncomplete = () => {
+        resolve();
+      };
+      tx.onerror = () => {
+        reject(tx.error ?? new Error("IndexedDB delete failed"));
+      };
+      tx.onabort = () => {
+        reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+      };
+    });
+  } catch {
+  } finally {
+    db?.close();
+  }
+}
+function validatePersistedSession(data) {
+  if (!data || typeof data !== "object") return null;
+  const s = data;
+  const kp = s.keyPair;
+  if (typeof s.tenant !== "string" || typeof s.accessToken !== "string" || typeof s.refreshToken !== "string" || typeof s.expiresAt !== "number" || !kp || !kp.privateKey || !kp.publicJwk) {
+    return null;
+  }
+  return data;
+}
 
 // src/sdk/pow.ts
 var BATCH_SIZE = 1e3;
@@ -173,17 +284,6 @@ async function solvePoW(challenge, difficulty) {
   return tryBatch();
 }
 
-// src/sdk/constants.ts
-var DEFAULT_TOKEN_TTL_SEC = 3600;
-var TOKEN_REFRESH_LEEWAY_MS = 12e4;
-var TOKEN_REFRESH_MIN_MS = 1e4;
-var RECONNECT_MAX_ATTEMPTS = 10;
-var RECONNECT_BASE_MS = 1e3;
-var RECONNECT_MAX_DELAY_MS = 3e4;
-var SUB_PROTOCOL = "access_token";
-var SDK_CACHE_MAX_ENTRIES_DEFAULT = 1e3;
-var SDK_POLL_INTERVAL_MS_DEFAULT = 5e3;
-
 // src/sdk/errors.ts
 var GeonicDBError = class extends Error {
   constructor(message, statusCode = 0) {
@@ -376,6 +476,14 @@ var _AuthManager = class _AuthManager {
     __publicField(this, "_dpopKeyPair", null);
     __publicField(this, "_dpopReady", null);
     __publicField(this, "_dpopNonce", null);
+    /**
+     * #1230: when true, every DPoP token mutation (login bind, refresh) is
+     * mirrored to IndexedDB so the session survives a page reload. Toggled
+     * by `login({ dpopPersist: true })` and `restoreSession()`.
+     */
+    __publicField(this, "_dpopPersist", false);
+    /** Email captured at login, persisted for UI display. */
+    __publicField(this, "_email", null);
     __publicField(this, "_tokenPromise", null);
     /** Callback to emit tokenRefresh events. Set by GeonicDB class. */
     __publicField(this, "onTokenRefresh", null);
@@ -402,9 +510,9 @@ var _AuthManager = class _AuthManager {
     this._anonymous = anonymous;
     if (!anonymous && dpopSupported) {
       this._dpopReady = generateDPoPKeyPair().then((kp) => {
-        this._dpopKeyPair = kp;
+        if (!this._dpopKeyPair) this._dpopKeyPair = kp;
       }).catch(() => {
-        this._dpopKeyPair = null;
+        if (!this._dpopKeyPair) this._dpopKeyPair = null;
       });
     }
   }
@@ -437,9 +545,23 @@ var _AuthManager = class _AuthManager {
   emitCacheEvent(name, payload) {
     this._emitCacheEvent?.(name, payload);
   }
-  /** Login with email and password (Bearer JWT). */
-  async login(email, password) {
+  /**
+   * Login with email and password (Bearer JWT).
+   *
+   * Pass `{ dpop: true }` to immediately exchange the Bearer session for a
+   * DPoP sender-constrained session via `/auth/dpop-bind` (RFC 9449). The
+   * returned tokens become unusable without this SDK instance's
+   * non-extractable private key, so a token leaked from storage (e.g.
+   * localStorage XSS) cannot be replayed from another origin.
+   */
+  async login(email, password, options) {
     this._log("login", email);
+    const wantsDpopPersist = options?.dpopPersist === true;
+    if (wantsDpopPersist && !options?.dpop) {
+      throw new AuthenticationError(
+        "dpopPersist: true requires dpop: true. Persisting Bearer tokens is the caller's responsibility (localStorage / sessionStorage)."
+      );
+    }
     const headers = {
       "Content-Type": "application/json"
     };
@@ -461,9 +583,81 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = Date.now() + (data.expiresIn - 60) * 1e3;
     this._tokenType = "Bearer";
     this._refreshToken = data.refreshToken;
+    this._email = email;
+    this._dpopPersist = wantsDpopPersist;
     this._invalidateAuthScopedState();
+    if (options?.dpop) {
+      const bound = await this._bindDpopSession();
+      if (this._dpopPersist) {
+        await this._persistDpopSession();
+      }
+      return bound;
+    }
     return data;
   }
+  /**
+   * Exchange the current Bearer session for a DPoP-bound session via
+   * `POST /auth/dpop-bind` (RFC 9449). The server re-issues access and
+   * refresh tokens with `cnf.jkt` matching this SDK's DPoP key pair.
+   *
+   * Assumes `_token` / `_refreshToken` are already populated by a prior
+   * `login()` call (callers should not invoke this directly).
+   *
+   * @internal
+   */
+  async _bindDpopSession() {
+    if (!this._token) {
+      throw new AuthenticationError(
+        "Cannot bind DPoP session: no Bearer token. login() must succeed first."
+      );
+    }
+    if (this._dpopReady) await this._dpopReady;
+    if (!this._dpopKeyPair) {
+      throw new AuthenticationError(
+        "DPoP binding requires a generated DPoP key pair, but key generation was unavailable or failed. DPoP requires Web Crypto subtle.generateKey."
+      );
+    }
+    const bindUrl = this._baseUrl + "/auth/dpop-bind";
+    const accessToken = this._token;
+    const data = await this._doDpopBind(bindUrl, accessToken, this._dpopNonce, 0);
+    this._token = data.accessToken;
+    this._tokenExpiry = Date.now() + (data.expiresIn - 60) * 1e3;
+    this._tokenType = "DPoP";
+    this._refreshToken = data.refreshToken;
+    this._invalidateAuthScopedState();
+    return { ...data, tokenType: "DPoP" };
+  }
+  async _doDpopBind(bindUrl, accessToken, dpopNonce, retryCount) {
+    const dpopProof = await createDPoPProof(
+      this._dpopKeyPair,
+      "POST",
+      bindUrl,
+      accessToken,
+      dpopNonce
+    );
+    if (!dpopProof) {
+      throw new AuthenticationError("DPoP proof generation failed");
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: "Bearer " + accessToken,
+      DPoP: dpopProof
+    };
+    if (this._tenant) headers["NGSILD-Tenant"] = this._tenant;
+    const res = await fetch(bindUrl, { method: "POST", headers });
+    const serverNonce = res.headers.get("DPoP-Nonce");
+    if (serverNonce) this._dpopNonce = serverNonce;
+    if (res.status === 401 && serverNonce && serverNonce !== dpopNonce && retryCount < _AuthManager.MAX_DPOP_RETRIES) {
+      return this._doDpopBind(bindUrl, accessToken, serverNonce, retryCount + 1);
+    }
+    if (!res.ok) {
+      const e = await res.json().catch(() => ({}));
+      throw new AuthenticationError(
+        e.detail || e.description || "DPoP bind failed: " + res.status
+      );
+    }
+    return await res.json();
+  }
   /**
    * Set credentials externally (e.g. from a login API response).
    * When tokenType is 'Bearer' and refreshToken is provided, all subsequent
@@ -490,9 +684,81 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = 0;
     this._refreshToken = null;
     this._tokenPromise = null;
+    this._email = null;
+    if (this._dpopPersist && this._tenant) {
+      void clearDPoPSession(this._tenant);
+    }
+    this._dpopPersist = false;
     this._anonymous = this._initialAnonymous;
     this._invalidateAuthScopedState();
   }
+  /**
+   * Restore a DPoP session previously persisted via `login({ dpop: true,
+   * dpopPersist: true })`. Returns true if a usable session was found and
+   * loaded into the SDK, false otherwise (no entry, IndexedDB unavailable,
+   * or the entry was for a different tenant).
+   *
+   * After a successful restore the SDK behaves as if `login()` had just
+   * succeeded: tokens are set, the DPoP key pair is rehydrated as a
+   * non-extractable `CryptoKey`, and subsequent requests automatically
+   * carry a fresh DPoP proof. Token refresh continues to flow through
+   * `/auth/refresh` and emits `tokenRefresh` events as usual.
+   *
+   * Token expiry is NOT validated here — the next `ensureToken()` call will
+   * trigger a refresh if the access token has expired (#1230). An expired
+   * refresh token will manifest as an `AuthenticationError` from that
+   * refresh attempt; consumers should treat such errors as "session ended,
+   * fall back to login()".
+   */
+  async restoreSession() {
+    if (this._initialAnonymous) return false;
+    if (!this._tenant) return false;
+    const persisted = await loadDPoPSession(this._tenant);
+    if (!persisted) return false;
+    if (persisted.tenant !== this._tenant) return false;
+    this._anonymous = false;
+    this._token = persisted.accessToken;
+    this._refreshToken = persisted.refreshToken;
+    this._tokenExpiry = persisted.expiresAt;
+    this._tokenType = "DPoP";
+    this._dpopKeyPair = persisted.keyPair;
+    this._dpopReady = Promise.resolve();
+    this._dpopNonce = null;
+    this._dpopPersist = true;
+    this._email = persisted.email ?? null;
+    this._tokenPromise = null;
+    this._invalidateAuthScopedState();
+    return true;
+  }
+  /**
+   * Whether this AuthManager currently has DPoP persistence enabled.
+   * Exposed for the `GeonicDB` wrapper to advertise behavior; internal
+   * consumers should read `_dpopPersist` directly.
+   */
+  isDpopPersisted() {
+    return this._dpopPersist;
+  }
+  /**
+   * Persist the current DPoP session to IndexedDB. Best-effort: a failed
+   * write is logged in debug mode but never propagated, since persistence
+   * is purely a UX optimization.
+   *
+   * @internal
+   */
+  async _persistDpopSession() {
+    if (!this._dpopPersist || !this._tenant || !this._dpopKeyPair || !this._token || !this._refreshToken) {
+      return;
+    }
+    const ok = await saveDPoPSession({
+      tenant: this._tenant,
+      accessToken: this._token,
+      refreshToken: this._refreshToken,
+      expiresAt: this._tokenExpiry,
+      email: this._email ?? void 0,
+      keyPair: this._dpopKeyPair
+    });
+    if (!ok) this._log("DPoP session persistence failed (IndexedDB unavailable?)");
+  }
   /**
    * Drop everything that may have been associated with the previous auth
    * context. Called on `login()` (after token assignment), `setCredentials()`,
@@ -535,12 +801,15 @@ var _AuthManager = class _AuthManager {
     return this._tokenPromise;
   }
   async _refreshBearerToken() {
-    this._log("refreshing Bearer token");
+    this._log("refreshing token (type=%s)", this._tokenType);
     try {
-      const res = await fetch(this._baseUrl + "/auth/refresh", {
+      const isDPoP = this._tokenType === "DPoP";
+      const refreshUrl = this._baseUrl + "/auth/refresh";
+      const body = JSON.stringify({ refreshToken: this._refreshToken });
+      const res = isDPoP ? await this._doDpopRefresh(refreshUrl, body, this._dpopNonce, 0) : await fetch(refreshUrl, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ refreshToken: this._refreshToken })
+        body
       });
       if (!res.ok) {
         this._refreshToken = null;
@@ -551,7 +820,7 @@ var _AuthManager = class _AuthManager {
       const data = await res.json();
       this._token = data.accessToken;
       this._tokenExpiry = Date.now() + (data.expiresIn - 60) * 1e3;
-      this._tokenType = "Bearer";
+      this._tokenType = data.tokenType ?? (isDPoP ? "DPoP" : "Bearer");
       this._refreshToken = data.refreshToken;
       this._tokenPromise = null;
       this.onTokenRefresh?.({
@@ -560,12 +829,51 @@ var _AuthManager = class _AuthManager {
         expiresIn: data.expiresIn,
         refreshToken: this._refreshToken
       });
+      if (this._dpopPersist) void this._persistDpopSession();
       return this._token;
     } catch (err) {
       this._tokenPromise = null;
       throw err;
     }
   }
+  /**
+   * Perform a DPoP-bound `/auth/refresh` call with the standard RFC 9449 §8
+   * `use_dpop_nonce` retry handshake.
+   *
+   * @internal
+   */
+  async _doDpopRefresh(refreshUrl, body, dpopNonce, retryCount) {
+    if (this._dpopReady) await this._dpopReady;
+    if (!this._dpopKeyPair) {
+      throw new AuthenticationError(
+        "DPoP-bound refresh requires a DPoP key pair, but key generation was unavailable."
+      );
+    }
+    const proof = await createDPoPProof(
+      this._dpopKeyPair,
+      "POST",
+      refreshUrl,
+      null,
+      dpopNonce
+    );
+    if (!proof) {
+      throw new AuthenticationError("DPoP proof generation failed");
+    }
+    const res = await fetch(refreshUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", DPoP: proof },
+      body
+    });
+    const serverNonce = res.headers.get("DPoP-Nonce");
+    if (serverNonce) this._dpopNonce = serverNonce;
+    if (res.status === 401 && serverNonce && serverNonce !== dpopNonce && retryCount < _AuthManager.MAX_DPOP_RETRIES) {
+      return this._doDpopRefresh(refreshUrl, body, serverNonce, retryCount + 1);
+    }
+    return res;
+  }
+  /* istanbul ignore next: PoW + DPoP token-exchange flow is exercised by E2E
+     against a live server. Unit-mocking each fetch + crypto step would not
+     verify the actual nonce/proof exchange. */
   async _acquireTokenViaPow() {
     try {
       if (this._dpopReady) await this._dpopReady;
@@ -602,6 +910,8 @@ var _AuthManager = class _AuthManager {
       throw err;
     }
   }
+  /* istanbul ignore next: DPoP nonce-retry handshake (RFC 9449 §8) — requires
+     a real server emitting `use_dpop_nonce` 400s. Exercised by E2E. */
   async _doTokenExchange(tokenUrl, tokenBody, dpopNonce, retryCount = 0) {
     const reqHeaders = {
       "Content-Type": "application/json"
@@ -1099,9 +1409,54 @@ var GeonicDB = class extends EventEmitter {
     }
   }
   // --- Authentication ---
-  /** Login with email and password (Bearer JWT). */
-  async login(email, password) {
-    return this._auth.login(email, password);
+  /**
+   * Login with email and password (Bearer JWT).
+   *
+   * Pass `{ dpop: true }` to immediately upgrade the session to a DPoP
+   * sender-constrained token (RFC 9449). Recommended for browser apps that
+   * persist tokens in storage exposed to XSS (localStorage / sessionStorage),
+   * since DPoP-bound tokens are unusable without this SDK instance's
+   * non-extractable private key.
+   *
+   * @example
+   * ```ts
+   * // Bearer (default, backward compatible)
+   * await db.login('user@example.com', 'password');
+   *
+   * // DPoP-bound (recommended for SPAs)
+   * await db.login('user@example.com', 'password', { dpop: true });
+   *
+   * // DPoP-bound + persisted across reloads (browser SPA UX)
+   * await db.login('user@example.com', 'password', {
+   *   dpop: true,
+   *   dpopPersist: true,
+   * });
+   * ```
+   */
+  async login(email, password, options) {
+    return this._auth.login(email, password, options);
+  }
+  /**
+   * Rehydrate a DPoP session previously persisted via
+   * `login({ dpop: true, dpopPersist: true })`.
+   *
+   * Returns true if a session for this tenant was found and loaded; false
+   * if there was no entry, IndexedDB is unavailable, or the persisted
+   * session was malformed. Call this at app startup before deciding
+   * whether to render the login form.
+   *
+   * @example
+   * ```ts
+   * const db = new GeonicDB({ baseUrl, tenant });
+   * if (await db.restoreSession()) {
+   *   // Tokens + DPoP private key recovered from IndexedDB — boot the app.
+   * } else {
+   *   // No session; show the login form.
+   * }
+   * ```
+   */
+  async restoreSession() {
+    return this._auth.restoreSession();
   }
   /**
    * Whether the SDK is currently operating in anonymous mode (no token held).