@geolonia/geonicdb-sdk 0.4.0 → 0.6.0

package/README.md

@@ -84,6 +84,36 @@ db.setCredentials({
 });
 ```
 
+### Anonymous Mode (public viewers)
+
+For public-facing apps such as GeoJSON viewers or BI dashboards that should
+serve **unregistered visitors** without forcing a login, pass `anonymous: true`
+to skip token acquisition entirely:
+
+```typescript
+const db = new GeonicDB({
+  baseUrl: 'https://your-geonicdb.example.com',
+  tenant: 'public',
+  anonymous: true, // no Authorization header, no /auth/nonce, no /oauth/token
+});
+
+// The server treats this as `role: 'anonymous'` and the XACML policy engine
+// decides whether to permit. Tenant admins must register a custom policy that
+// permits the anonymous role for the resources to expose — the default
+// ANONYMOUS_DEFAULT_POLICY denies everything.
+const entities = await db.getEntities({ type: 'GeoJSON' });
+```
+
+- `apiKey` and `anonymous: true` cannot be combined (constructor throws).
+- `db.login()` upgrades the SDK out of anonymous mode (Bearer JWT).
+- `db.setCredentials({ token, tokenType: 'Bearer', ... })` upgrades from
+  anonymous. **`tokenType: 'DPoP'` is rejected** for anonymous-built instances
+  (no DPoP key pair is generated for them) — use a non-anonymous SDK instance
+  for DPoP credentials.
+- `db.logout()` reverts back to anonymous (`db.isAnonymous() === true` again).
+- WebSocket `db.connect()` is **not supported** in anonymous mode — call
+  `login()` / `setCredentials()` first.
+
 ## Entity CRUD
 
 ```typescript
@@ -178,7 +208,7 @@ await db.connect();
 | `tokenRefresh` | `RefreshedCredentials` | Bearer token was refreshed |
 | `cacheHit` | `CacheEvent` | Request served from in-memory cache (304 received) |
 | `cacheMiss` | `CacheEvent` | Cache miss — fresh response fetched from origin |
-| `cacheInvalidated` | `CacheEvent` | Cache entry dropped (e.g. after a WebSocket entity event) |
+| `cacheInvalidated` | `CacheEvent` | Cache entry dropped via explicit `clearCache()`. WebSocket entity events do **not** trigger cache invalidation — see "Client-side Cache & Polling" |
 
 ## Client-side Cache & Polling
 
@@ -204,6 +234,26 @@ const [a, b, c] = await Promise.all([
 
 Cache is enabled by default; pass `cache: false` to opt out.
 
+### Cache lifetime under WebSocket activity
+
+WebSocket entity events (`entityCreated` / `entityUpdated` / `entityDeleted`)
+do **not** automatically invalidate the SDK cache. This is intentional:
+
+- Data endpoints respond with `Cache-Control: private, no-cache`, so every
+  cached read already revalidates with the origin via `If-None-Match`.
+- If the entity actually changed, the server's freshly computed `ETag` will
+  not match the client's `If-None-Match` → server returns `200` with the
+  fresh body → SDK replaces the cache entry.
+- If the WebSocket event was noisy / unrelated to a particular cached query
+  (or the data hasn't propagated to the read replica yet), the server returns
+  `304 Not Modified` → SDK serves the cached body with no body bytes
+  transferred.
+
+Deleting cache entries on every WebSocket event would force the next read to
+miss the cache and fetch a full `200` body — defeating the bandwidth-saving
+`304` path. To force a full reset (e.g. on auth change), call `clearCache()`
+explicitly.
+
 ### Polling
 
 `db.poll(params, options)` repeats `getEntities()` at an interval and reports
@@ -222,12 +272,6 @@ const handle = db.poll({ type: 'Room' }, {
 handle.stop();
 ```
 
-### WebSocket-driven cache invalidation
-
-When the SDK receives `entityCreated` / `entityUpdated` / `entityDeleted`
-WebSocket events, it drops affected cache entries automatically. The next
-read re-validates with the server.
-
 ## API Reference
 
 ### Constructor
@@ -247,14 +291,16 @@ read re-validates with the server.
 | `debug` | `boolean` | No | Enable debug logging to console (default: `false`) |
 | `cache` | `boolean` | No | Enable in-memory cache with ETag/304 + request dedup (default: `true`) |
 | `cacheMaxEntries` | `number` | No | LRU cache capacity when `cache` is enabled (default: `1000`) |
+| `anonymous` | `boolean` | No | Anonymous mode — skip token acquisition and send no `Authorization` header. Cannot be combined with `apiKey`. See [Anonymous Mode](#anonymous-mode-public-viewers) (default: `false`) |
 
 ### Authentication
 
 | Method | Parameters | Returns | Description |
 |--------|-----------|---------|-------------|
-| `login(email, password)` | `string, string` | `Promise<LoginResponse>` | Login with email and password (Bearer JWT) |
-| `setCredentials(opts)` | `CredentialsOptions` | `this` | Set credentials externally (e.g. from a login API response) |
-| `logout()` | — | `void` | Clear all credentials and disconnect WebSocket |
+| `login(email, password)` | `string, string` | `Promise<LoginResponse>` | Login with email and password (Bearer JWT). Upgrades the SDK out of anonymous mode |
+| `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` |
 
 ### Entity CRUD
 

package/geonicdb.cjs

@@ -347,11 +347,27 @@ function isCacheableMethod(method) {
 
 // src/sdk/auth.ts
 var _AuthManager = class _AuthManager {
-  constructor(baseUrl, apiKey, tenant, debug = false) {
+  constructor(baseUrl, apiKey, tenant, debug = false, anonymous = false) {
     __publicField(this, "_baseUrl");
     __publicField(this, "_apiKey");
     __publicField(this, "_tenant");
     __publicField(this, "_debug");
+    /**
+     * #1105: anonymous モード。true の場合、トークンを取得せず Authorization
+     * ヘッダ無しで送信する。サーバー側 (`optionalAuth`) で role='anonymous' として
+     * 通り、XACML が認可判定する。
+     *
+     * `_initialAnonymous` はコンストラクタで指定された希望モード (immutable)。
+     * `_anonymous` は現在のモード状態で、`login()` / `setCredentials()` で false
+     * に降り、`logout()` で `_initialAnonymous` の値に戻る。
+     *
+     * トークン有無 (`_token === null`) からは推論しない。`_token` は refresh
+     * 失敗時に null へ落ちるが、ユーザが明示的に `logout()` していない以上、
+     * 次のリクエストを勝手に Authorization ヘッダ無しで送ってはならない
+     * (#1113 review)。
+     */
+    __publicField(this, "_initialAnonymous");
+    __publicField(this, "_anonymous");
     __publicField(this, "_token", null);
     __publicField(this, "_tokenExpiry", 0);
     __publicField(this, "_tokenType", "Bearer");
@@ -372,11 +388,18 @@ var _AuthManager = class _AuthManager {
     __publicField(this, "_emitCacheEvent", null);
     /** In-flight request map keyed by `${METHOD}:${path}` for request deduplication. */
     __publicField(this, "_inFlight", /* @__PURE__ */ new Map());
+    if (anonymous && apiKey) {
+      throw new Error(
+        "GeonicDB SDK: `anonymous: true` cannot be combined with `apiKey`. Anonymous mode skips token acquisition entirely."
+      );
+    }
     this._baseUrl = baseUrl;
     this._apiKey = apiKey;
     this._tenant = tenant;
     this._debug = debug;
-    if (dpopSupported) {
+    this._initialAnonymous = anonymous;
+    this._anonymous = anonymous;
+    if (!anonymous && dpopSupported) {
       this._dpopReady = generateDPoPKeyPair().then((kp) => {
         this._dpopKeyPair = kp;
       }).catch(() => {
@@ -384,6 +407,16 @@ var _AuthManager = class _AuthManager {
       });
     }
   }
+  /**
+   * True when running unauthenticated.
+   *
+   * Returns the explicit mode flag, NOT derived from `_token === null`. After
+   * a refresh failure clears `_token`, the SDK must NOT silently switch to
+   * anonymous; the caller must explicitly `logout()` to revert (#1113 review).
+   */
+  isAnonymous() {
+    return this._anonymous;
+  }
   _log(...args) {
     if (this._debug) console.log("[GeonicDB]", ...args);
   }
@@ -422,6 +455,7 @@ var _AuthManager = class _AuthManager {
       );
     }
     const data = await res.json();
+    this._anonymous = false;
     this._token = data.accessToken;
     this._tokenExpiry = Date.now() + (data.expiresIn - 60) * 1e3;
     this._tokenType = "Bearer";
@@ -436,6 +470,12 @@ var _AuthManager = class _AuthManager {
    */
   setCredentials(opts) {
     if (!opts || !opts.token) throw new Error("token is required");
+    if (this._initialAnonymous && opts.tokenType === "DPoP") {
+      throw new Error(
+        "DPoP credentials cannot be set on an SDK instance constructed with `anonymous: true` (no DPoP key pair is generated for anonymous instances). Use Bearer credentials, or construct the SDK in non-anonymous mode."
+      );
+    }
+    this._anonymous = false;
     this._token = opts.token;
     this._tokenType = opts.tokenType || "Bearer";
     this._tokenExpiry = opts.expiresIn != null ? Date.now() + (opts.expiresIn - 60) * 1e3 : Date.now() + DEFAULT_TOKEN_TTL_SEC * 1e3;
@@ -449,6 +489,7 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = 0;
     this._refreshToken = null;
     this._tokenPromise = null;
+    this._anonymous = this._initialAnonymous;
     this._invalidateAuthScopedState();
   }
   /**
@@ -461,7 +502,13 @@ var _AuthManager = class _AuthManager {
     this._cache?.clear();
     this._inFlight.clear();
   }
-  /** Ensure a valid token is available, refreshing or acquiring as needed. */
+  /**
+   * Ensure a valid token is available, refreshing or acquiring as needed.
+   *
+   * #1105: In anonymous mode (no apiKey, no Bearer credentials) this throws
+   * `AuthenticationError`. Callers that may run anonymously should branch on
+   * `isAnonymous()` first instead of calling `ensureToken()` blindly.
+   */
   async ensureToken() {
     if (this._token && Date.now() < this._tokenExpiry) {
       return this._token;
@@ -473,6 +520,16 @@ var _AuthManager = class _AuthManager {
       this._tokenPromise = this._refreshBearerToken();
       return this._tokenPromise;
     }
+    if (this._anonymous) {
+      throw new AuthenticationError(
+        "Anonymous mode: no token available. Call login() or setCredentials() to authenticate."
+      );
+    }
+    if (!this._apiKey) {
+      throw new AuthenticationError(
+        "No authentication method available. Call login() / setCredentials() to authenticate, or construct the SDK with an apiKey."
+      );
+    }
     this._tokenPromise = this._acquireTokenViaPow();
     return this._tokenPromise;
   }
@@ -593,7 +650,7 @@ var _AuthManager = class _AuthManager {
   async request(method, path, body) {
     this._log(method, path);
     if (!this._cache || !isCacheableMethod(method) || body !== void 0) {
-      const token = await this.ensureToken();
+      const token = this.isAnonymous() ? null : await this.ensureToken();
       const res = await this._doAuthenticatedRequest(method, path, body, token);
       this._log(method, path, "\u2192", res.status);
       return res;
@@ -614,14 +671,14 @@ var _AuthManager = class _AuthManager {
   async _cachedRequest(method, path, key) {
     const cache = this._cache;
     if (!cache) {
-      const token2 = await this.ensureToken();
+      const token2 = this.isAnonymous() ? null : await this.ensureToken();
       return this._doAuthenticatedRequest(method, path, void 0, token2);
     }
     const cached = cache.get(key);
     const conditional = {};
     if (cached?.etag) conditional["If-None-Match"] = cached.etag;
     if (cached?.lastModified) conditional["If-Modified-Since"] = cached.lastModified;
-    const token = await this.ensureToken();
+    const token = this.isAnonymous() ? null : await this.ensureToken();
     const res = await this._doAuthenticatedRequest(method, path, void 0, token, 0, conditional);
     this._log(method, path, "\u2192", res.status);
     if (res.status === 304 && cached) {
@@ -662,11 +719,19 @@ var _AuthManager = class _AuthManager {
     return res;
   }
   async _doAuthenticatedRequest(method, path, body, token, retryCount = 0, extraHeaders = {}) {
+    if (this._tokenType === "DPoP" && token !== null) {
+      if (this._dpopReady) await this._dpopReady;
+      if (!this._dpopKeyPair) {
+        throw new AuthenticationError(
+          "DPoP credentials require a generated DPoP key pair, but key generation was unavailable or failed."
+        );
+      }
+    }
     const url = this._baseUrl + path;
-    const isDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair;
+    const isDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair && token !== null;
     const bodyStr = body !== void 0 ? JSON.stringify(body) : void 0;
     const doRequest = async (reqToken, dpopNonce) => {
-      const reqIsDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair;
+      const reqIsDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair && reqToken !== null;
       const dpopProof = reqIsDPoP ? await createDPoPProof(
         this._dpopKeyPair,
         method,
@@ -675,11 +740,13 @@ var _AuthManager = class _AuthManager {
         dpopNonce
       ) : null;
       const headers = {
-        Authorization: (reqIsDPoP ? "DPoP " : "Bearer ") + reqToken,
         "Content-Type": "application/ld+json",
         Accept: "application/ld+json",
         ...extraHeaders
       };
+      if (reqToken !== null) {
+        headers["Authorization"] = (reqIsDPoP ? "DPoP " : "Bearer ") + reqToken;
+      }
       if (dpopProof) headers["DPoP"] = dpopProof;
       if (this._tenant) headers["Fiware-Service"] = this._tenant;
       return fetch(url, { method, headers, body: bodyStr });
@@ -689,11 +756,12 @@ var _AuthManager = class _AuthManager {
     const previousNonce = this._dpopNonce;
     const newNonce = res.headers.get("DPoP-Nonce");
     if (newNonce) this._dpopNonce = newNonce;
+    const canRetry401 = currentToken !== null;
     if (res.status === 401 && isDPoP && newNonce && newNonce !== previousNonce) {
       res = await doRequest(currentToken, newNonce);
       const rn = res.headers.get("DPoP-Nonce");
       if (rn) this._dpopNonce = rn;
-      if (res.status === 401) {
+      if (res.status === 401 && canRetry401) {
         this._token = null;
         this._tokenPromise = null;
         currentToken = await this.ensureToken();
@@ -701,7 +769,7 @@ var _AuthManager = class _AuthManager {
         const fn = res.headers.get("DPoP-Nonce");
         if (fn) this._dpopNonce = fn;
       }
-    } else if (res.status === 401) {
+    } else if (res.status === 401 && canRetry401) {
       this._token = null;
       this._tokenPromise = null;
       currentToken = await this.ensureToken();
@@ -750,6 +818,13 @@ var WebSocketManager = class {
   }
   /** Establish WebSocket connection (authentication is automatic). */
   async connect() {
+    if (this._auth.isAnonymous()) {
+      const err = new Error(
+        "WebSocket connect() is not supported in anonymous mode. Authenticate via login() or setCredentials() before connect()."
+      );
+      this._emit("error", err);
+      throw err;
+    }
     if (this._reconnectTimer) {
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;
@@ -985,7 +1060,7 @@ var GeonicDB = class extends EventEmitter {
       if (!tenant) tenant = script?.getAttribute?.("data-tenant") || "";
       if (!baseUrl) baseUrl = script?.getAttribute?.("data-base-url") || "";
     }
-    this._auth = new AuthManager(baseUrl, apiKey, tenant, opts.debug);
+    this._auth = new AuthManager(baseUrl, apiKey, tenant, opts.debug, opts.anonymous);
     this._auth.onTokenRefresh = (creds) => {
       this.onTokenRefresh?.(creds);
       this.emit("tokenRefresh", creds);
@@ -1001,44 +1076,39 @@ var GeonicDB = class extends EventEmitter {
       tenant,
       (event, data) => {
         this.emit(event, data);
-        if (event === "entityCreated" || event === "entityUpdated" || event === "entityDeleted") {
-          this._invalidateCacheForEntityEvent(data);
-        }
       },
       opts.wsEndpoint
     );
   }
   /**
-   * Drop cache entries that may have been affected by an entity change.
+   * Drop every cached response. Useful in tests and on manual auth changes.
    *
-   * The SDK does not know which lists exactly contain the entity, so the
-   * conservative strategy is to drop all NGSI-LD / NGSIv2 entity-related
-   * paths. ETag re-validation on the next read brings the data back in one
-   * round trip with `If-None-Match`, so this remains efficient even when
-   * over-invalidating.
+   * Emits a `cacheInvalidated` event for each removed entry so listeners can
+   * track explicit flushes (the WebSocket-driven auto-invalidation was removed
+   * in #1060 to preserve the ETag/304 revalidation path; `clearCache()` is now
+   * the only path that emits this event).
    */
-  _invalidateCacheForEntityEvent(event) {
+  clearCache() {
     const cache = this._auth.getCache();
     if (!cache) return;
-    const entityId = event?.entityId;
-    const removed = cache.deleteWhere((key) => {
-      if (key.includes("/ngsi-ld/v1/entities") || key.includes("/v2/entities")) return true;
-      if (entityId && key.includes(entityId)) return true;
-      return false;
-    });
+    const removed = cache.deleteWhere(() => true);
     for (const key of removed) {
       this._auth.emitCacheEvent("cacheInvalidated", { key, path: key.split(":").slice(1).join(":") });
     }
   }
-  /** Drop every cached response. Useful in tests and on manual auth changes. */
-  clearCache() {
-    this._auth.getCache()?.clear();
-  }
   // --- Authentication ---
   /** Login with email and password (Bearer JWT). */
   async login(email, password) {
     return this._auth.login(email, password);
   }
+  /**
+   * Whether the SDK is currently operating in anonymous mode (no token held).
+   * Returns true only when `anonymous: true` was passed to the constructor
+   * AND no credentials have been set via `login()` / `setCredentials()`.
+   */
+  isAnonymous() {
+    return this._auth.isAnonymous();
+  }
   /**
    * Set credentials externally (e.g. from a login API response).
    * When tokenType is 'Bearer' with a refreshToken, DPoP/PoW is bypassed entirely.