@attlaz/client 1.106.1 → 1.107.0

package/dist/Client.d.ts

@@ -1,6 +1,6 @@
 import { OAuthClientToken } from './Http/OAuthClientToken.js';
 import { ITransport, ParseErrorHandler } from './Http/Transport/ITransport.js';
-import { OAuthClient } from './Http/Transport/OAuthClient.js';
+import { OAuthClient, TokenChangeHandler } from './Http/Transport/OAuthClient.js';
 import { AccessTokenEndpoint } from './Service/AccessTokenEndpoint.js';
 import { AdapterConnectionEndpoint } from './Service/AdapterConnectionEndpoint.js';
 import { AdapterEndpoint } from './Service/AdapterEndpoint.js';
@@ -91,6 +91,13 @@ export declare class Client {
     getToken(): OAuthClientToken | null;
     setToken(token: OAuthClientToken): void;
     unsetAccessToken(): void;
+    /**
+     * Observe tokens the client acquires or discards on its own — see {@link TokenChangeHandler}.
+     * A consumer that persists the token must use this rather than reading getToken() after a call:
+     * refresh tokens rotate, so a refreshed token that is not written back is replayed later and
+     * rejected. Pass null to stop observing. OAuth-only; a custom transport has no token.
+     */
+    setTokenChangeHandler(handler: TokenChangeHandler | null): void;
     getApiInformation(): Promise<{
         version: string;
     }>;

package/dist/Client.js

@@ -184,6 +184,15 @@ export class Client {
     unsetAccessToken() {
         this.httpClient.unsetToken();
     }
+    /**
+     * Observe tokens the client acquires or discards on its own — see {@link TokenChangeHandler}.
+     * A consumer that persists the token must use this rather than reading getToken() after a call:
+     * refresh tokens rotate, so a refreshed token that is not written back is replayed later and
+     * rejected. Pass null to stop observing. OAuth-only; a custom transport has no token.
+     */
+    setTokenChangeHandler(handler) {
+        this.httpClient.setTokenChangeHandler(handler);
+    }
     async getApiInformation() {
         const result = await this.httpClient.request('/system/health', null, 'GET', false);
         if (result.version === undefined) {

package/dist/Http/Transport/OAuthClient.d.ts

@@ -3,10 +3,20 @@ import { Parameters } from '../Data/Parameters.js';
 import { OAuthClientOptions } from '../OAuthClientOptions.js';
 import { OAuthClientToken } from '../OAuthClientToken.js';
 import { ITransport, ParseErrorHandler } from './ITransport.js';
+/**
+ * Invoked whenever the client changes the token by itself: after a successful authenticate or
+ * refresh (the server rotates refresh tokens, so the previous one is revoked at that moment), and
+ * with null when a refresh is rejected and the session is gone. A consumer that persists the token
+ * must listen here — reading getToken() after a call is too late, because a rotated token that is
+ * never written back is replayed later and rejected. Not invoked for setToken()/unsetToken(), which
+ * are the caller's own writes.
+ */
+export type TokenChangeHandler = (token: OAuthClientToken | null) => void;
 export declare class OAuthClient implements ITransport {
     private readonly options;
     private debug;
     private oauthClientToken;
+    private tokenChangeHandler;
     private tokenAcquisitionPromise;
     private version;
     private parseErrorHandler;
@@ -43,6 +53,16 @@ export declare class OAuthClient implements ITransport {
     getToken(): OAuthClientToken | null;
     setToken(token: OAuthClientToken): void;
     unsetToken(): void;
+    /**
+     * Observe tokens the client acquires or discards on its own. See {@link TokenChangeHandler}.
+     * Pass null to stop observing.
+     */
+    setTokenChangeHandler(handler: TokenChangeHandler | null): void;
+    /**
+     * The single place the client updates its own token, so no acquisition path can change it
+     * without the handler hearing about it.
+     */
+    private applyToken;
     enableDebug(): void;
     disableDebug(): void;
     isDebugEnabled(): boolean;

package/dist/Http/Transport/OAuthClient.js

@@ -9,6 +9,7 @@ export class OAuthClient {
     options;
     debug = false;
     oauthClientToken = null;
+    tokenChangeHandler = null;
     // Single-flight guard for token acquisition (initial client-credentials auth or refresh), so
     // concurrent requests share one in-flight acquisition instead of each hitting the token endpoint.
     tokenAcquisitionPromise = null;
@@ -34,7 +35,7 @@ export class OAuthClient {
                     params.client_secret = this.options.clientSecret;
                 }
                 const rawAuthToken = await this.requestToken(params);
-                this.oauthClientToken = this.tokenToOauthClientToken(rawAuthToken);
+                this.applyToken(this.tokenToOauthClientToken(rawAuthToken));
                 return true;
             }
             if (this.options.clientId !== null && this.options.clientSecret !== null) {
@@ -45,7 +46,7 @@ export class OAuthClient {
                     client_secret: this.options.clientSecret,
                     scope: this.options.scopes.join(' '),
                 });
-                this.oauthClientToken = this.tokenToOauthClientToken(rawAuthToken);
+                this.applyToken(this.tokenToOauthClientToken(rawAuthToken));
             }
             return true;
         }
@@ -77,7 +78,7 @@ export class OAuthClient {
                 params.client_secret = this.options.clientSecret;
             }
             const rawAuthToken = await this.requestToken(params);
-            this.oauthClientToken = this.tokenToOauthClientToken(rawAuthToken);
+            this.applyToken(this.tokenToOauthClientToken(rawAuthToken));
         }
         catch (e) {
             if (e instanceof ClientError) {
@@ -88,6 +89,11 @@ export class OAuthClient {
                 // error. Transient failures (network / 5xx) are rethrown unchanged so a
                 // hiccup doesn't force a logout.
                 if (e.httpStatus !== null && e.httpStatus >= 400 && e.httpStatus < 500) {
+                    // Drop the rejected token: keeping it means every later request retries the
+                    // same dead refresh token, and the server's firewall blocks the IP after a
+                    // handful of those. A confidential client re-mints via client_credentials on
+                    // the next request; a public one now fails fast with 401 instead of looping.
+                    this.applyToken(null);
                     throw new ClientError('Refresh token rejected, re-authentication required', HttpStatus.HTTP_UNAUTHORIZED);
                 }
                 throw e;
@@ -258,6 +264,32 @@ export class OAuthClient {
     unsetToken() {
         this.oauthClientToken = null;
     }
+    /**
+     * Observe tokens the client acquires or discards on its own. See {@link TokenChangeHandler}.
+     * Pass null to stop observing.
+     */
+    setTokenChangeHandler(handler) {
+        this.tokenChangeHandler = handler;
+    }
+    /**
+     * The single place the client updates its own token, so no acquisition path can change it
+     * without the handler hearing about it.
+     */
+    applyToken(token) {
+        this.oauthClientToken = token;
+        if (this.tokenChangeHandler === null) {
+            return;
+        }
+        try {
+            this.tokenChangeHandler(token);
+        }
+        catch (error) {
+            // A consumer's persistence failure must not fail the authentication that succeeded —
+            // the token in memory is valid either way. Report it: silently dropping it would hide
+            // exactly the stale-token bug this handler exists to prevent.
+            console.error('[OAuthClient] Token change handler threw', { error });
+        }
+    }
     enableDebug() {
         this.debug = true;
     }

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { ITransport } from './Http/Transport/ITransport.js';
 export { DirectTransport } from './Http/Transport/DirectTransport.js';
 export type { DirectTransportRoute } from './Http/Transport/DirectTransport.js';
 export { OAuthClient } from './Http/Transport/OAuthClient.js';
+export type { TokenChangeHandler } from './Http/Transport/OAuthClient.js';
 export { OAuthClientOptions } from './Http/OAuthClientOptions.js';
 export { OAuthClientToken } from './Http/OAuthClientToken.js';
 export { ClientError } from './Http/ClientError.js';

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.106.0";
+export declare const VERSION = "1.107.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "1.106.0";
+export const VERSION = "1.107.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attlaz/client",
-  "version": "1.106.1",
+  "version": "1.107.0",
   "description": "Javascript Client to access Attlaz API",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",