@geolonia/geonicdb-sdk 0.10.1 → 0.11.1

package/README.md

@@ -96,58 +96,39 @@ 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.
+Sessions are **DPoP sender-constrained automatically** (RFC 9449). After
+`POST /auth/login` succeeds, the SDK transparently exchanges the Bearer
+session for a DPoP-bound one, generating a non-extractable ECDSA P-256 key
+pair via Web Crypto and binding the access / refresh tokens to it. A token
+leaked from storage (e.g. localStorage XSS) therefore cannot be replayed
+from another origin. There is no DPoP option to set — you never deal with
+DPoP directly.
 
 ```typescript
-const result = await db.login('user@example.com', 'password', { dpop: true });
-// result.tokenType === 'DPoP'
+const result = await db.login('user@example.com', 'password');
+// result.tokenType === 'DPoP' when Web Crypto is available.
 // 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);
+// The bind step and the RFC 9449 §8 `use_dpop_nonce` handshake are internal.
 ```
 
-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.
+On runtimes without Web Crypto (`subtle.generateKey`, e.g. a non-HTTPS
+context), the session cannot be sender-constrained: the SDK silently keeps
+the plain Bearer session and **login still succeeds** (`tokenType === 'Bearer'`).
 
-#### Persisting DPoP across page reloads
+#### Keeping the user signed in 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.
+By default a session is held in memory only — reloading the page loses it
+and forces the user to log in again. Pass `{ rememberSession: true }` to keep
+the user signed in:
 
 ```typescript
 const db = new GeonicDB({ baseUrl, tenant });
-await db.login('user@example.com', 'password', {
-  dpop: true,
-  dpopPersist: true,
-});
+await db.login('user@example.com', 'password', { rememberSession: true });
 
 // On the next page load:
 const db2 = new GeonicDB({ baseUrl, tenant });
 if (await db2.restoreSession()) {
-  // Session was rehydrated from IndexedDB — boot the app.
+  // Session was rehydrated — boot the app.
 } else {
   // No persisted session; show the login form.
 }
@@ -156,14 +137,19 @@ if (await db2.restoreSession()) {
 await db2.logout();
 ```
 
+Under the hood, the session is persisted to **IndexedDB**. The structured
+clone algorithm stores the DPoP `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.
+
 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.
+- Persistence is best-effort: a failed IDB write (or no Web Crypto, so the
+  session stays Bearer) does not break login — it just means no rehydrate.
+- Opt-in by design: shared-device flows should leave `rememberSession` off.
 - iOS Safari may evict IndexedDB under ITP after 7 days of no user
   interaction with the origin.
 
@@ -403,8 +389,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. 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 |
+| `login(email, password, options?)` | `string, string, LoginOptions?` | `Promise<LoginResponse>` | Login with email and password. Upgrades the SDK out of anonymous mode. The session is DPoP sender-constrained (RFC 9449) **automatically and transparently** — no option to set; silently falls back to Bearer when Web Crypto is unavailable. Pass `{ rememberSession: true }` to keep the user signed in across page reloads (persisted to IndexedDB) |
+| `restoreSession()` | — | `Promise<boolean>` | Rehydrate a session previously persisted via `login({ rememberSession: 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` |
@@ -428,6 +414,7 @@ handle.stop();
 | `limit` | `number` | Max results |
 | `offset` | `number` | Pagination offset |
 | `q` | `string` | NGSI-LD query expression |
+| `options` | `string` | NGSI-LD representation options (comma-separated): `sysAttrs` (include `createdAt`/`modifiedAt`), `keyValues`, `concise`, `normalized` |
 
 #### `CountEntitiesParams`
 
@@ -467,6 +454,7 @@ handle.stop();
 | `timerel` | `string` | Temporal relation (`before`, `after`, `between`) |
 | `limit` | `number` | Max results |
 | `offset` | `number` | Pagination offset |
+| `options` | `string` | NGSI-LD representation options (comma-separated): `sysAttrs`, `temporalValues`, `aggregatedValues` |
 
 ### Batch Operations
 

package/geonicdb.cjs

@@ -477,11 +477,12 @@ var _AuthManager = class _AuthManager {
     __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 _AuthManager = class _AuthManager {
     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 _AuthManager = class _AuthManager {
     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 _AuthManager = class _AuthManager {
     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 _AuthManager = class _AuthManager {
     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 _AuthManager = class _AuthManager {
    * @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 _AuthManager = class _AuthManager {
         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 GeonicDB = class extends EventEmitter {
   }
   // --- 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 GeonicDB = class 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.
    * }