@geolonia/geonicdb-sdk 0.8.0 → 0.10.0

package/geonicdb.d.ts

@@ -19,6 +19,7 @@ export type {
   GeonicDBOptions,
   GetEntitiesParams,
   GetTemporalEntitiesParams,
+  LoginOptions,
   LoginResponse,
   PollHandle,
   PollOptions,

package/geonicdb.iife.js

@@ -72,8 +72,23 @@ var GeonicDBModule = (() => {
     }
   };
 
+  // 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 @@ var GeonicDBModule = (() => {
     );
     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 @@ var GeonicDBModule = (() => {
     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 GeonicDBModule = (() => {
       __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 GeonicDBModule = (() => {
       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 GeonicDBModule = (() => {
     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 GeonicDBModule = (() => {
       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 GeonicDBModule = (() => {
       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 GeonicDBModule = (() => {
       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 GeonicDBModule = (() => {
         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 GeonicDBModule = (() => {
           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 GeonicDBModule = (() => {
         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 GeonicDBModule = (() => {
       }
     }
     // --- 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).