@geolonia/geonicdb-sdk 0.10.1 → 0.11.0

package/geonicdb.d.ts

@@ -171,37 +171,20 @@ export interface ReconnectingEvent {
 /** Options for `db.login(...)`. */
 export interface LoginOptions {
 	/**
-	 * If true, immediately exchange the Bearer session for a DPoP-bound
-	 * sender-constrained session via `POST /auth/dpop-bind` (RFC 9449).
+	 * If true, keep the user signed in across page reloads by persisting the
+	 * session to IndexedDB. After a reload, call `db.restoreSession()` to
+	 * rehydrate the session; `db.logout()` clears the persisted entry.
 	 *
-	 * Recommended for browser apps that persist tokens in storage that may be
-	 * exposed to XSS (localStorage, sessionStorage). DPoP-bound tokens are
-	 * unusable without the client's non-extractable private key, so a stolen
-	 * token cannot be replayed from another origin.
-	 *
-	 * Throws `AuthenticationError` if DPoP is not supported in the runtime
-	 * (no Web Crypto subtle.generateKey).
-	 *
-	 * Default: false (Bearer remains).
-	 */
-	dpop?: boolean;
-	/**
-	 * If true, persist the DPoP session (non-extractable private key + tokens)
-	 * to IndexedDB so the session survives a page reload. Implies `dpop: true`
-	 * — passing `dpopPersist: true` without `dpop: true` throws.
-	 *
-	 * The private key is stored as a `CryptoKey` via the structured clone
-	 * algorithm; `extractable: false` is preserved, so the key cannot be read
-	 * back as JWK / PEM even with full DOM access. A token leaked from
-	 * localStorage remains unusable without this SDK origin's IndexedDB.
-	 *
-	 * After a reload, call `db.restoreSession()` to rehydrate. Use `db.logout()`
-	 * to clear the persisted entry.
+	 * The session is bound to a non-extractable key (DPoP, RFC 9449) stored via
+	 * the structured clone algorithm — `extractable: false` is preserved, so the
+	 * key cannot be read back as JWK / PEM even with full DOM access. A token
+	 * leaked from localStorage stays unusable without this origin's IndexedDB.
 	 *
 	 * Default: false. Opt-out by design: shared-device flows should not enable
-	 * this.
+	 * this. Has no effect when the runtime lacks Web Crypto — the session cannot
+	 * be sender-constrained, so it is not persisted.
 	 */
-	dpopPersist?: boolean;
+	rememberSession?: boolean;
 }
 /** Response from the login endpoint. */
 export interface LoginResponse {
@@ -364,33 +347,27 @@ export declare class GeonicDB extends EventEmitter {
 	 */
 	clearCache(): void;
 	/**
-	 * Login with email and password (Bearer JWT).
+	 * Login with email and password.
 	 *
-	 * 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.
+	 * The session is sender-constrained with DPoP (RFC 9449) automatically and
+	 * transparently — there is no DPoP option to set. A token leaked from
+	 * storage (e.g. localStorage XSS) is therefore unusable from another origin.
+	 * On runtimes without Web Crypto, the SDK silently keeps a plain Bearer
+	 * session and login still succeeds.
 	 *
 	 * @example
 	 * ```ts
-	 * // Bearer (default, backward compatible)
+	 * // Standard login — DPoP applied transparently when supported.
 	 * 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,
-	 * });
+	 * // Keep the user signed in across page reloads (browser SPA UX).
+	 * await db.login('user@example.com', 'password', { rememberSession: true });
 	 * ```
 	 */
 	login(email: string, password: string, options?: LoginOptions): Promise<LoginResponse>;
 	/**
-	 * Rehydrate a DPoP session previously persisted via
-	 * `login({ dpop: true, dpopPersist: true })`.
+	 * Rehydrate a session previously persisted via
+	 * `login(email, password, { rememberSession: 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
@@ -401,7 +378,7 @@ export declare class GeonicDB extends EventEmitter {
 	 * ```ts
 	 * const db = new GeonicDB({ baseUrl, tenant });
 	 * if (await db.restoreSession()) {
-	 *   // Tokens + DPoP private key recovered from IndexedDB — boot the app.
+	 *   // Session (tokens + non-extractable key) recovered — boot the app.
 	 * } else {
 	 *   // No session; show the login form.
 	 * }

package/geonicdb.iife.js

@@ -477,11 +477,12 @@ var GeonicDBModule = (() => {
       __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()`.
+       * When true, every DPoP token mutation (login bind, refresh) is mirrored to
+       * IndexedDB so the session survives a page reload (#1230). Toggled by
+       * `login(email, password, { rememberSession: true })` and
+       * `restoreSession()` (#1244).
        */
-      __publicField(this, "_dpopPersist", false);
+      __publicField(this, "_rememberSession", false);
       /** Email captured at login, persisted for UI display. */
       __publicField(this, "_email", null);
       __publicField(this, "_tokenPromise", null);
@@ -546,22 +547,22 @@ var GeonicDBModule = (() => {
       this._emitCacheEvent?.(name, payload);
     }
     /**
-     * Login with email and password (Bearer JWT).
+     * Login with email and password.
      *
-     * 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.
+     * #1244: DPoP (RFC 9449) is transparent and always-on — there is no `dpop`
+     * option to set. After the Bearer login succeeds, the SDK automatically
+     * exchanges it for a DPoP sender-constrained session so a token leaked from
+     * storage (e.g. localStorage XSS) cannot be replayed from another origin.
+     *
+     * When the runtime lacks Web Crypto (`crypto.subtle.generateKey`, e.g. a
+     * non-HTTPS context), DPoP cannot be used and the SDK silently keeps the
+     * Bearer session — login still succeeds. Callers never deal with DPoP
+     * directly; pass `{ rememberSession: true }` only to keep the user signed in
+     * across reloads.
      */
     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 wantsRemember = options?.rememberSession === true;
       const headers = {
         "Content-Type": "application/json"
       };
@@ -584,14 +585,30 @@ var GeonicDBModule = (() => {
       this._tokenType = "Bearer";
       this._refreshToken = data.refreshToken;
       this._email = email;
-      this._dpopPersist = wantsDpopPersist;
+      this._rememberSession = wantsRemember;
       this._invalidateAuthScopedState();
-      if (options?.dpop) {
-        const bound = await this._bindDpopSession();
-        if (this._dpopPersist) {
-          await this._persistDpopSession();
+      if (!wantsRemember && this._tenant) {
+        void clearDPoPSession(this._tenant);
+      }
+      if (this._dpopReady) await this._dpopReady;
+      if (this._dpopKeyPair) {
+        try {
+          const bound = await this._bindDpopSession();
+          if (this._rememberSession) {
+            await this._persistDpopSession();
+          }
+          return bound;
+        } catch (err) {
+          this._token = null;
+          this._tokenExpiry = 0;
+          this._tokenType = "Bearer";
+          this._refreshToken = null;
+          this._tokenPromise = null;
+          this._rememberSession = false;
+          this._email = null;
+          this._invalidateAuthScopedState();
+          throw err;
         }
-        return bound;
       }
       return data;
     }
@@ -685,18 +702,19 @@ var GeonicDBModule = (() => {
       this._refreshToken = null;
       this._tokenPromise = null;
       this._email = null;
-      if (this._dpopPersist && this._tenant) {
+      if (this._tenant) {
         void clearDPoPSession(this._tenant);
       }
-      this._dpopPersist = false;
+      this._rememberSession = 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).
+     * Restore a session previously persisted via
+     * `login(email, password, { rememberSession: 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
@@ -724,19 +742,19 @@ var GeonicDBModule = (() => {
       this._dpopKeyPair = persisted.keyPair;
       this._dpopReady = Promise.resolve();
       this._dpopNonce = null;
-      this._dpopPersist = true;
+      this._rememberSession = 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.
+     * Whether this AuthManager currently keeps the session persisted across
+     * reloads (`rememberSession`). Exposed for the `GeonicDB` wrapper; internal
+     * consumers should read `_rememberSession` directly.
      */
-    isDpopPersisted() {
-      return this._dpopPersist;
+    isSessionRemembered() {
+      return this._rememberSession;
     }
     /**
      * Persist the current DPoP session to IndexedDB. Best-effort: a failed
@@ -746,7 +764,7 @@ var GeonicDBModule = (() => {
      * @internal
      */
     async _persistDpopSession() {
-      if (!this._dpopPersist || !this._tenant || !this._dpopKeyPair || !this._token || !this._refreshToken) {
+      if (!this._rememberSession || !this._tenant || !this._dpopKeyPair || !this._token || !this._refreshToken) {
         return;
       }
       const ok = await saveDPoPSession({
@@ -829,7 +847,7 @@ var GeonicDBModule = (() => {
           expiresIn: data.expiresIn,
           refreshToken: this._refreshToken
         });
-        if (this._dpopPersist) void this._persistDpopSession();
+        if (this._rememberSession) void this._persistDpopSession();
         return this._token;
       } catch (err) {
         this._tokenPromise = null;
@@ -1410,35 +1428,29 @@ var GeonicDBModule = (() => {
     }
     // --- Authentication ---
     /**
-     * Login with email and password (Bearer JWT).
+     * Login with email and password.
      *
-     * 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.
+     * The session is sender-constrained with DPoP (RFC 9449) automatically and
+     * transparently — there is no DPoP option to set. A token leaked from
+     * storage (e.g. localStorage XSS) is therefore unusable from another origin.
+     * On runtimes without Web Crypto, the SDK silently keeps a plain Bearer
+     * session and login still succeeds.
      *
      * @example
      * ```ts
-     * // Bearer (default, backward compatible)
+     * // Standard login — DPoP applied transparently when supported.
      * 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,
-     * });
+     * // Keep the user signed in across page reloads (browser SPA UX).
+     * await db.login('user@example.com', 'password', { rememberSession: 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 })`.
+     * Rehydrate a session previously persisted via
+     * `login(email, password, { rememberSession: 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
@@ -1449,7 +1461,7 @@ var GeonicDBModule = (() => {
      * ```ts
      * const db = new GeonicDB({ baseUrl, tenant });
      * if (await db.restoreSession()) {
-     *   // Tokens + DPoP private key recovered from IndexedDB — boot the app.
+     *   // Session (tokens + non-extractable key) recovered — boot the app.
      * } else {
      *   // No session; show the login form.
      * }