@geolonia/geonicdb-sdk 0.7.1 → 0.9.0

package/README.md

@@ -96,6 +96,34 @@ 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.
+
 ### External Token
 
 ```typescript
@@ -146,8 +174,20 @@ await db.createEntity({ id: 'urn:ngsi-ld:Room:001', type: 'Room', ... });
 // Read
 const entity = await db.getEntity('urn:ngsi-ld:Room:001');
 
-// Query
-const entities = await db.getEntities({ type: 'Room', limit: 10 });
+// Query (NGSI-LD §5.7.2 のクエリパラメータを網羅)
+const entities = await db.getEntities({
+  type: 'Room',
+  limit: 10,
+  // scopeQ: '/OpenData;/OpenData/#',     // exact + descendants
+  // georel: 'near;maxDistance==1000',
+  // geometry: 'Point',
+  // coordinates: '139.7,35.6',
+  // attrs: 'name,location',
+  // pick: 'name', omit: 'createdAt',
+  // lang: 'ja',
+  // orderBy: 'modifiedAt', orderDirection: 'desc',
+  // count: true,
+});
 
 // Update
 await db.updateEntity('urn:ngsi-ld:Room:001', { temperature: { type: 'Property', value: 25 } });
@@ -320,7 +360,7 @@ 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 |
 | `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

@@ -31,6 +31,7 @@ __export(index_exports, {
   NotFoundError: () => NotFoundError,
   RateLimitError: () => RateLimitError,
   ValidationError: () => ValidationError,
+  buildPathWithParams: () => buildPathWithParams,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -436,8 +437,16 @@ 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 headers = {
       "Content-Type": "application/json"
@@ -461,8 +470,75 @@ var _AuthManager = class _AuthManager {
     this._tokenType = "Bearer";
     this._refreshToken = data.refreshToken;
     this._invalidateAuthScopedState();
+    if (options?.dpop) {
+      const bound = await this._bindDpopSession();
+      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
@@ -534,12 +610,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;
@@ -550,7 +629,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?.({
@@ -565,6 +644,44 @@ var _AuthManager = class _AuthManager {
       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;
@@ -601,6 +718,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"
@@ -872,6 +991,7 @@ var WebSocketManager = class {
     if (options) {
       if (options.entityTypes) msg.entityTypes = options.entityTypes;
       if (options.idPattern) msg.idPattern = options.idPattern;
+      if (options.scopeQ) msg.scopeQ = options.scopeQ;
     }
     this._subscription = msg;
     if (this._pendingSubscription) return;
@@ -1097,9 +1217,26 @@ 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 });
+   * ```
+   */
+  async login(email, password, options) {
+    return this._auth.login(email, password, options);
   }
   /**
    * Whether the SDK is currently operating in anonymous mode (no token held).
@@ -1224,14 +1361,14 @@ var GeonicDB = class extends EventEmitter {
   }
   /** Count entities matching the given filters. */
   async count(params) {
-    const parts = ["count=true", "limit=0"];
-    if (params?.type) parts.push("type=" + encodeURIComponent(params.type));
-    if (params?.q) parts.push("q=" + encodeURIComponent(params.q));
-    const qs = "?" + parts.join("&");
-    const res = await this._auth.request(
-      "GET",
-      "/ngsi-ld/v1/entities" + qs
-    );
+    const path = buildPathWithParams("/ngsi-ld/v1/entities", {
+      count: true,
+      limit: 0,
+      type: params?.type,
+      q: params?.q,
+      scopeQ: params?.scopeQ
+    });
+    const res = await this._auth.request("GET", path);
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
       throw createErrorFromResponse(res.status, e, "Count failed");
@@ -1290,24 +1427,11 @@ var GeonicDB = class extends EventEmitter {
   // --- Temporal API ---
   /** Query temporal entities. */
   async getTemporalEntities(params) {
-    let qs = "";
-    if (params) {
-      const parts = [];
-      if (params.type) parts.push("type=" + encodeURIComponent(params.type));
-      if (params.id) parts.push("id=" + encodeURIComponent(params.id));
-      if (params.idPattern) parts.push("idPattern=" + encodeURIComponent(params.idPattern));
-      if (params.attrs) parts.push("attrs=" + encodeURIComponent(params.attrs));
-      if (params.q) parts.push("q=" + encodeURIComponent(params.q));
-      if (params.timeproperty) parts.push("timeproperty=" + encodeURIComponent(params.timeproperty));
-      if (params.timeAt) parts.push("timeAt=" + encodeURIComponent(params.timeAt));
-      if (params.endTimeAt) parts.push("endTimeAt=" + encodeURIComponent(params.endTimeAt));
-      if (params.timerel) parts.push("timerel=" + encodeURIComponent(params.timerel));
-      if (params.limit != null) parts.push("limit=" + params.limit);
-      if (params.offset != null) parts.push("offset=" + params.offset);
-      if (parts.length) qs = "?" + parts.join("&");
-    }
     return this._jsonGet(
-      "/ngsi-ld/v1/temporal/entities" + qs,
+      buildPathWithParams(
+        "/ngsi-ld/v1/temporal/entities",
+        params
+      ),
       "Temporal query failed"
     );
   }
@@ -1375,6 +1499,11 @@ var GeonicDB = class extends EventEmitter {
   /**
    * Make an authenticated API request.
    * Automatically checks response status, parses JSON, and throws on error.
+   *
+   * Empty bodies (`Content-Length: 0` 含む) は Content-Type に関係なく `null`
+   * を返す (#1145)。NGSI-LD の POST / DELETE / PATCH 系は仕様上ボディが
+   * 空だが、サーバ実装が `Content-Type: application/ld+json` を付けて返す
+   * ケースがあり、そこで `res.json()` が SyntaxError を投げて止まっていた。
    */
   async request(method, path, body) {
     const res = await this._auth.request(method, path, body);
@@ -1382,9 +1511,15 @@ var GeonicDB = class extends EventEmitter {
       const e = await res.json().catch(() => ({}));
       throw createErrorFromResponse(res.status, e, "Request failed: " + res.status);
     }
+    if (res.status === 204) return null;
+    if (res.headers.get("Content-Length") === "0") return null;
     const ct = res.headers.get("Content-Type") || "";
-    if (res.status === 204 || !ct) return null;
-    if (ct.indexOf("json") !== -1) return res.json();
+    if (!ct) return null;
+    if (ct.indexOf("json") !== -1) {
+      const text = await res.text();
+      if (!text) return null;
+      return JSON.parse(text);
+    }
     return res.text();
   }
   /**
@@ -1421,12 +1556,28 @@ if (typeof window !== "undefined") {
   window.GeonicDB = GeonicDB;
 }
 function buildEntitiesPath(params) {
-  if (!params) return "/ngsi-ld/v1/entities";
-  const parts = [];
-  if (params.type) parts.push("type=" + encodeURIComponent(params.type));
-  if (params.limit != null) parts.push("limit=" + params.limit);
-  if (params.offset != null) parts.push("offset=" + params.offset);
-  if (params.q) parts.push("q=" + encodeURIComponent(params.q));
-  return parts.length > 0 ? "/ngsi-ld/v1/entities?" + parts.join("&") : "/ngsi-ld/v1/entities";
+  return buildPathWithParams(
+    "/ngsi-ld/v1/entities",
+    params
+  );
+}
+function buildPathWithParams(path, params) {
+  if (!params) return path;
+  const sp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    if (typeof value === "boolean") {
+      sp.append(key, value ? "true" : "false");
+    } else if (typeof value === "number") {
+      sp.append(key, String(value));
+    } else if (typeof value === "string") {
+      if (value === "") continue;
+      sp.append(key, value);
+    } else {
+      continue;
+    }
+  }
+  const qs = sp.toString();
+  return qs ? `${path}?${qs}` : path;
 }
 //# sourceMappingURL=geonicdb.cjs.map