@geolonia/geonicdb-sdk 0.9.0 → 0.10.0

package/README.md

@@ -124,6 +124,49 @@ Notes:
 - 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
@@ -360,7 +403,8 @@ handle.stop();
 
 | Method | Parameters | Returns | Description |
 |--------|-----------|---------|-------------|
-| `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 |
+| `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;
       });
     }
   }
@@ -448,6 +556,12 @@ var _AuthManager = class _AuthManager {
    */
   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"
     };
@@ -469,9 +583,14 @@ 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;
@@ -565,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()`,
@@ -638,6 +829,7 @@ var _AuthManager = class _AuthManager {
         expiresIn: data.expiresIn,
         refreshToken: this._refreshToken
       });
+      if (this._dpopPersist) void this._persistDpopSession();
       return this._token;
     } catch (err) {
       this._tokenPromise = null;
@@ -1233,11 +1425,39 @@ var GeonicDB = class extends EventEmitter {
    *
    * // 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).
    * Returns true only when `anonymous: true` was passed to the constructor