@cratis/chronicle 2.1.0 → 3.0.0

package/connection/TokenProvider.spec.ts

@@ -0,0 +1,159 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { OAuthTokenResponse } from './fetchOAuthAccessToken';
+import { OAuthTokenProvider } from './TokenProvider';
+
+// Long enough to stay outside the 60s refresh margin for the whole spec.
+const longLifetime = 3600;
+// Short enough to be inside the refresh margin immediately.
+const shortLifetime = 30;
+
+const token = (value: string, expiresIn?: number | string): OAuthTokenResponse =>
+    ({ access_token: value, ...(expiresIn === undefined ? {} : { expires_in: expiresIn }) });
+
+/**
+ * Creates a provider whose token fetches are served from the given script of
+ * responses — the last one repeats for any further fetches.
+ */
+function createProvider(responses: Array<OAuthTokenResponse | Error>) {
+    let call = 0;
+    const fetchToken = vi.fn(() => {
+        const response = responses[Math.min(call++, responses.length - 1)];
+        return response instanceof Error ? Promise.reject(response) : Promise.resolve(response);
+    });
+
+    const provider = new OAuthTokenProvider('https://localhost:35000/connect/token', 'client', 'secret', true, fetchToken);
+    return { provider, fetchToken };
+}
+
+describe('OAuthTokenProvider', () => {
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    describe('when requesting the first token', () => {
+        it('should fetch it lazily and return it', async () => {
+            const { provider, fetchToken } = createProvider([token('token-1', longLifetime)]);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(fetchToken).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('when the cached token is fresh', () => {
+        it('should serve it without fetching again', async () => {
+            const { provider, fetchToken } = createProvider([token('token-1', longLifetime), token('token-2', longLifetime)]);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(fetchToken).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('when the token response has no expires_in', () => {
+        it('should assume the default lifetime and cache the token', async () => {
+            const { provider, fetchToken } = createProvider([token('token-1')]);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(fetchToken).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('when the token response sends expires_in as a string', () => {
+        it('should parse it and cache the token', async () => {
+            const { provider, fetchToken } = createProvider([token('token-1', '3600')]);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(fetchToken).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('when the token enters the refresh margin', () => {
+        it('should refresh ahead of expiry', async () => {
+            const { provider, fetchToken } = createProvider([token('token-1', shortLifetime), token('token-2', shortLifetime)]);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+
+            // The short lifetime is already inside the margin, so the next request
+            // refreshes even though the first token has not expired yet.
+            expect(await provider.getAccessToken()).toBe('token-2');
+            expect(fetchToken).toHaveBeenCalledTimes(2);
+        });
+    });
+
+    describe('when a refresh fails while the cached token is still valid', () => {
+        it('should keep serving the cached token', async () => {
+            const { provider } = createProvider([token('token-1', shortLifetime), new Error('unavailable')]);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+
+            // Refresh is due (inside the margin) and fails — the token is still valid
+            // for another 30s, so it must keep flowing rather than dropping auth.
+            expect(await provider.getAccessToken()).toBe('token-1');
+        });
+    });
+
+    describe('when no token can be fetched', () => {
+        it('should return undefined instead of rejecting', async () => {
+            const { provider } = createProvider([new Error('unavailable')]);
+
+            // The RPC proceeds and fails with the server's auth rejection — that is
+            // the session machinery's problem, not the token provider's.
+            expect(await provider.getAccessToken()).toBeUndefined();
+        });
+
+        it('should throttle further fetch attempts', async () => {
+            const { provider, fetchToken } = createProvider([new Error('unavailable')]);
+
+            expect(await provider.getAccessToken()).toBeUndefined();
+            expect(await provider.getAccessToken()).toBeUndefined();
+
+            // The second request arrives well inside the retry delay — one attempt,
+            // not one per RPC (the session answers a keepalive every second).
+            expect(fetchToken).toHaveBeenCalledTimes(1);
+        });
+
+        it('should try again once the retry delay has passed', async () => {
+            vi.useFakeTimers();
+            const { provider, fetchToken } = createProvider([new Error('unavailable'), token('token-1', longLifetime)]);
+
+            expect(await provider.getAccessToken()).toBeUndefined();
+            vi.advanceTimersByTime(5000);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(fetchToken).toHaveBeenCalledTimes(2);
+        });
+    });
+
+    describe('when multiple requests race', () => {
+        it('should share a single fetch', async () => {
+            let resolveFetch!: (response: OAuthTokenResponse) => void;
+            const fetchToken = vi.fn(() => new Promise<OAuthTokenResponse>(resolve => {
+                resolveFetch = resolve;
+            }));
+            const provider = new OAuthTokenProvider('https://localhost:35000/connect/token', 'client', 'secret', true, fetchToken);
+
+            const first = provider.getAccessToken();
+            const second = provider.getAccessToken();
+            resolveFetch(token('token-1', longLifetime));
+
+            expect(await first).toBe('token-1');
+            expect(await second).toBe('token-1');
+            expect(fetchToken).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('when a refresh is forced', () => {
+        it('should discard the cached token and fetch a new one', async () => {
+            const { provider, fetchToken } = createProvider([token('token-1', longLifetime), token('token-2', longLifetime)]);
+
+            expect(await provider.getAccessToken()).toBe('token-1');
+            expect(await provider.refresh()).toBe('token-2');
+            expect(fetchToken).toHaveBeenCalledTimes(2);
+        });
+    });
+});

package/connection/TokenProvider.ts

@@ -1,11 +1,16 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import * as http from 'http';
-import * as https from 'https';
+import { diag } from '@opentelemetry/api';
+import { fetchOAuthAccessToken, type OAuthTokenResponse } from './fetchOAuthAccessToken';
 
-const TOKEN_EXPIRY_BUFFER_SECONDS = 60;
+// Refresh once the token has less than this long left before it expires.
+const TOKEN_REFRESH_MARGIN_MS = 60_000;
+// Assumed lifetime when the token response carries no usable expires_in.
 const DEFAULT_TOKEN_EXPIRY_SECONDS = 3600;
+// Minimum pause between failed fetch attempts, so an auth outage does not turn
+// every RPC into a token request.
+const FAILED_FETCH_RETRY_DELAY_MS = 5_000;
 
 /**
  * Interface for providing authentication tokens.
@@ -13,6 +18,10 @@ const DEFAULT_TOKEN_EXPIRY_SECONDS = 3600;
 export interface ITokenProvider {
     /**
      * Gets the current access token.
+     *
+     * Never rejects — when no token can be obtained the result is undefined, the RPC
+     * proceeds without authorization and fails with the server's rejection, which the
+     * session machinery recovers from.
      * @returns Promise resolving to the access token or undefined if not available.
      */
     getAccessToken(): Promise<string | undefined>;
@@ -37,28 +46,46 @@ export class NoOpTokenProvider implements ITokenProvider {
     }
 }
 
-interface OAuthTokenResponse {
-    access_token: string;
-    expires_in: number;
-}
-
 /**
- * OAuth token provider using client credentials flow.
+ * OAuth token provider using the client credentials flow.
+ *
+ * Owns the access token so it can be attached to every RPC individually instead of
+ * being baked into the channel at connect time: the token is fetched lazily on first
+ * use, cached, and refreshed once it enters the refresh margin ahead of expiry, so
+ * token expiry never invalidates the channel. A failed refresh falls back to the
+ * cached token while it is still actually valid — only the refresh margin has been
+ * crossed, not the expiry — and further attempts are throttled so an unreachable
+ * auth endpoint does not turn every RPC into a fetch attempt.
  */
 export class OAuthTokenProvider implements ITokenProvider {
+    private readonly _logger = diag.createComponentLogger({
+        namespace: '@cratis/chronicle/OAuthTokenProvider'
+    });
+
     private _accessToken?: string;
-    private _tokenExpiry = new Date(0);
+    private _expiresAt = 0;
+    private _lastFailedFetch?: number;
     private _refreshPromise?: Promise<string | undefined>;
 
+    /**
+     * Creates a new {@link OAuthTokenProvider}.
+     * @param tokenEndpoint - The OAuth2 token endpoint to request tokens from.
+     * @param clientId - The client identifier.
+     * @param clientSecret - The client secret.
+     * @param skipTlsValidation - Whether to skip TLS certificate chain validation.
+     * @param _fetchToken - Test-only seam replacing the OAuth2 token request.
+     */
     constructor(
-        private readonly _tokenEndpoint: string,
-        private readonly _clientId: string,
-        private readonly _clientSecret: string,
-        private readonly _skipTlsValidation: boolean = true
+        tokenEndpoint: string,
+        clientId: string,
+        clientSecret: string,
+        skipTlsValidation: boolean = true,
+        private readonly _fetchToken: () => Promise<OAuthTokenResponse> = () =>
+            fetchOAuthAccessToken(tokenEndpoint, clientId, clientSecret, skipTlsValidation)
     ) {}
 
     async getAccessToken(): Promise<string | undefined> {
-        if (this._accessToken && new Date() < this._tokenExpiry) {
+        if (this.hasFreshToken()) {
             return this._accessToken;
         }
 
@@ -66,7 +93,11 @@ export class OAuthTokenProvider implements ITokenProvider {
             return this._refreshPromise;
         }
 
-        this._refreshPromise = this.fetchAccessToken();
+        if (this.isThrottled()) {
+            return this.cachedTokenWhileValid();
+        }
+
+        this._refreshPromise = this.fetchAndCacheAccessToken();
         try {
             return await this._refreshPromise;
         } finally {
@@ -76,65 +107,45 @@ export class OAuthTokenProvider implements ITokenProvider {
 
     async refresh(): Promise<string | undefined> {
         this._accessToken = undefined;
-        this._tokenExpiry = new Date(0);
+        this._expiresAt = 0;
+        this._lastFailedFetch = undefined;
         return this.getAccessToken();
     }
 
-    private async fetchAccessToken(): Promise<string | undefined> {
-        const params = new URLSearchParams();
-        params.append('grant_type', 'client_credentials');
-        params.append('client_id', this._clientId);
-        params.append('client_secret', this._clientSecret);
-
-        const body = params.toString();
-
-        return new Promise((resolve, reject) => {
-            const url = new URL(this._tokenEndpoint);
-            const isHttps = url.protocol === 'https:';
-            const httpModule = isHttps ? https : http;
-
-            const req = httpModule.request(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded',
-                    'Content-Length': Buffer.byteLength(body)
-                },
-                // Chain validation is skipped only when skipTlsValidation is explicitly set,
-                // matching the gRPC channel's credentials for the same connection string.
-                ...(isHttps && this._skipTlsValidation ? { rejectUnauthorized: false } : {})
-            }, response => {
-                let data = '';
-
-                response.on('data', chunk => {
-                    data += chunk;
-                });
-
-                response.on('end', () => {
-                    if (response.statusCode !== 200) {
-                        reject(new Error(`Token request failed with status ${response.statusCode}: ${data}`));
-                        return;
-                    }
-
-                    try {
-                        const tokenResponse = JSON.parse(data) as OAuthTokenResponse;
-                        this._accessToken = tokenResponse.access_token;
-                        const expiresInSeconds = tokenResponse.expires_in || DEFAULT_TOKEN_EXPIRY_SECONDS;
-                        this._tokenExpiry = new Date(Date.now() + (expiresInSeconds - TOKEN_EXPIRY_BUFFER_SECONDS) * 1000);
-                        resolve(this._accessToken);
-                    } catch (error) {
-                        reject(new Error(`Failed to parse token response: ${error instanceof Error ? error.message : String(error)}`));
-                    }
-                });
-            });
+    private hasFreshToken(): boolean {
+        return !!this._accessToken && this._expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS;
+    }
 
-            req.on('error', error => {
-                reject(new Error(`Token request failed: ${error.message}`));
+    private isThrottled(): boolean {
+        return this._lastFailedFetch !== undefined && Date.now() - this._lastFailedFetch < FAILED_FETCH_RETRY_DELAY_MS;
+    }
+
+    private cachedTokenWhileValid(): string | undefined {
+        return this._accessToken && Date.now() < this._expiresAt ? this._accessToken : undefined;
+    }
+
+    private async fetchAndCacheAccessToken(): Promise<string | undefined> {
+        try {
+            const response = await this._fetchToken();
+            this._accessToken = response.access_token;
+            this._expiresAt = Date.now() + this.lifetimeSecondsFrom(response) * 1000;
+            this._lastFailedFetch = undefined;
+            return this._accessToken;
+        } catch (error) {
+            this._logger.warn('Failed to fetch OAuth2 token', {
+                error: error instanceof Error ? error.message : String(error)
             });
+            this._lastFailedFetch = Date.now();
+            return this.cachedTokenWhileValid();
+        }
+    }
 
-            req.write(body);
-            req.end();
-        });
+    // expires_in is RECOMMENDED but not required by OAuth2, and some servers send it
+    // as a string.
+    private lifetimeSecondsFrom(response: OAuthTokenResponse): number {
+        const seconds = Number(response.expires_in);
+        return Number.isFinite(seconds) && seconds > 0 ? seconds : DEFAULT_TOKEN_EXPIRY_SECONDS;
     }
 }
 
-export type TokenProvider = ITokenProvider;
+export type TokenProvider = ITokenProvider;

package/connection/fetchOAuthAccessToken.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import * as http from 'http';
+import * as https from 'https';
+
+/**
+ * The shape of a successful OAuth2 token response.
+ */
+export interface OAuthTokenResponse {
+    access_token: string;
+
+    /** RECOMMENDED but not required by OAuth2, and some servers send it as a string. */
+    expires_in?: number | string;
+}
+
+/**
+ * Requests an access token from an OAuth2 token endpoint using the client credentials flow.
+ * @param tokenEndpoint - The token endpoint URL.
+ * @param clientId - The client identifier.
+ * @param clientSecret - The client secret.
+ * @param skipTlsValidation - Whether to skip TLS certificate chain validation.
+ * @returns The parsed token response; rejects when the request fails or the response is not a valid token.
+ */
+export function fetchOAuthAccessToken(
+    tokenEndpoint: string,
+    clientId: string,
+    clientSecret: string,
+    skipTlsValidation: boolean
+): Promise<OAuthTokenResponse> {
+    const params = new URLSearchParams();
+    params.append('grant_type', 'client_credentials');
+    params.append('client_id', clientId);
+    params.append('client_secret', clientSecret);
+
+    const body = params.toString();
+
+    return new Promise((resolve, reject) => {
+        const url = new URL(tokenEndpoint);
+        const isHttps = url.protocol === 'https:';
+        const httpModule = isHttps ? https : http;
+
+        const request = httpModule.request(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Length': Buffer.byteLength(body)
+            },
+            // Chain validation is skipped only when skipTlsValidation is explicitly set,
+            // matching the gRPC channel's credentials for the same connection string.
+            ...(isHttps && skipTlsValidation ? { rejectUnauthorized: false } : {})
+        }, response => {
+            let data = '';
+
+            response.on('data', chunk => {
+                data += chunk;
+            });
+
+            response.on('end', () => {
+                if (response.statusCode !== 200) {
+                    reject(new Error(`Token request failed with status ${response.statusCode}: ${data}`));
+                    return;
+                }
+
+                try {
+                    const tokenResponse = JSON.parse(data) as OAuthTokenResponse;
+                    if (!tokenResponse.access_token) {
+                        reject(new Error('Token response did not contain an access_token'));
+                        return;
+                    }
+
+                    resolve(tokenResponse);
+                } catch (error) {
+                    reject(new Error(`Failed to parse token response: ${error instanceof Error ? error.message : String(error)}`));
+                }
+            });
+        });
+
+        request.on('error', error => {
+            reject(new Error(`Token request failed: ${error.message}`));
+        });
+
+        request.write(body);
+        request.end();
+    });
+}

package/dist/connection/TokenProvider.d.ts

@@ -1,9 +1,14 @@
+import { type OAuthTokenResponse } from './fetchOAuthAccessToken';
 /**
  * Interface for providing authentication tokens.
  */
 export interface ITokenProvider {
     /**
      * Gets the current access token.
+     *
+     * Never rejects — when no token can be obtained the result is undefined, the RPC
+     * proceeds without authorization and fails with the server's rejection, which the
+     * session machinery recovers from.
      * @returns Promise resolving to the access token or undefined if not available.
      */
     getAccessToken(): Promise<string | undefined>;
@@ -21,20 +26,39 @@ export declare class NoOpTokenProvider implements ITokenProvider {
     refresh(): Promise<string | undefined>;
 }
 /**
- * OAuth token provider using client credentials flow.
+ * OAuth token provider using the client credentials flow.
+ *
+ * Owns the access token so it can be attached to every RPC individually instead of
+ * being baked into the channel at connect time: the token is fetched lazily on first
+ * use, cached, and refreshed once it enters the refresh margin ahead of expiry, so
+ * token expiry never invalidates the channel. A failed refresh falls back to the
+ * cached token while it is still actually valid — only the refresh margin has been
+ * crossed, not the expiry — and further attempts are throttled so an unreachable
+ * auth endpoint does not turn every RPC into a fetch attempt.
  */
 export declare class OAuthTokenProvider implements ITokenProvider {
-    private readonly _tokenEndpoint;
-    private readonly _clientId;
-    private readonly _clientSecret;
-    private readonly _skipTlsValidation;
+    private readonly _fetchToken;
+    private readonly _logger;
     private _accessToken?;
-    private _tokenExpiry;
+    private _expiresAt;
+    private _lastFailedFetch?;
     private _refreshPromise?;
-    constructor(_tokenEndpoint: string, _clientId: string, _clientSecret: string, _skipTlsValidation?: boolean);
+    /**
+     * Creates a new {@link OAuthTokenProvider}.
+     * @param tokenEndpoint - The OAuth2 token endpoint to request tokens from.
+     * @param clientId - The client identifier.
+     * @param clientSecret - The client secret.
+     * @param skipTlsValidation - Whether to skip TLS certificate chain validation.
+     * @param _fetchToken - Test-only seam replacing the OAuth2 token request.
+     */
+    constructor(tokenEndpoint: string, clientId: string, clientSecret: string, skipTlsValidation?: boolean, _fetchToken?: () => Promise<OAuthTokenResponse>);
     getAccessToken(): Promise<string | undefined>;
     refresh(): Promise<string | undefined>;
-    private fetchAccessToken;
+    private hasFreshToken;
+    private isThrottled;
+    private cachedTokenWhileValid;
+    private fetchAndCacheAccessToken;
+    private lifetimeSecondsFrom;
 }
 export type TokenProvider = ITokenProvider;
 //# sourceMappingURL=TokenProvider.d.ts.map

package/dist/connection/TokenProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TokenProvider.d.ts","sourceRoot":"","sources":["../../connection/TokenProvider.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;OAGG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IAC9C,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAI7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAG/C;AAOD;;GAEG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IAMjD,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IARvC,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAC,CAA8B;gBAGjC,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,kBAAkB,GAAE,OAAc;IAGjD,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAiB7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;YAM9B,gBAAgB;CAuDjC;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC"}
+{"version":3,"file":"TokenProvider.d.ts","sourceRoot":"","sources":["../../connection/TokenProvider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAUzF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;OAOG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IAC9C,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAI7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAG/C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IAuBjD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAtBhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAErB;IAEH,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAClC,OAAO,CAAC,eAAe,CAAC,CAA8B;IAEtD;;;;;;;OAOG;gBAEC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,iBAAiB,GAAE,OAAc,EAChB,WAAW,GAAE,MAAM,OAAO,CAAC,kBAAkB,CACqB;IAGjF,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAqB7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAO5C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,qBAAqB;YAIf,wBAAwB;IAkBtC,OAAO,CAAC,mBAAmB;CAI9B;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC"}

package/dist/connection/TokenProvider.js

@@ -1,9 +1,14 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
-import * as http from 'http';
-import * as https from 'https';
-const TOKEN_EXPIRY_BUFFER_SECONDS = 60;
+import { diag } from '@opentelemetry/api';
+import { fetchOAuthAccessToken } from './fetchOAuthAccessToken';
+// Refresh once the token has less than this long left before it expires.
+const TOKEN_REFRESH_MARGIN_MS = 60_000;
+// Assumed lifetime when the token response carries no usable expires_in.
 const DEFAULT_TOKEN_EXPIRY_SECONDS = 3600;
+// Minimum pause between failed fetch attempts, so an auth outage does not turn
+// every RPC into a token request.
+const FAILED_FETCH_RETRY_DELAY_MS = 5_000;
 /**
  * No-op token provider for when authentication is not required.
  */
@@ -16,30 +21,47 @@ export class NoOpTokenProvider {
     }
 }
 /**
- * OAuth token provider using client credentials flow.
+ * OAuth token provider using the client credentials flow.
+ *
+ * Owns the access token so it can be attached to every RPC individually instead of
+ * being baked into the channel at connect time: the token is fetched lazily on first
+ * use, cached, and refreshed once it enters the refresh margin ahead of expiry, so
+ * token expiry never invalidates the channel. A failed refresh falls back to the
+ * cached token while it is still actually valid — only the refresh margin has been
+ * crossed, not the expiry — and further attempts are throttled so an unreachable
+ * auth endpoint does not turn every RPC into a fetch attempt.
  */
 export class OAuthTokenProvider {
-    _tokenEndpoint;
-    _clientId;
-    _clientSecret;
-    _skipTlsValidation;
+    _fetchToken;
+    _logger = diag.createComponentLogger({
+        namespace: '@cratis/chronicle/OAuthTokenProvider'
+    });
     _accessToken;
-    _tokenExpiry = new Date(0);
+    _expiresAt = 0;
+    _lastFailedFetch;
     _refreshPromise;
-    constructor(_tokenEndpoint, _clientId, _clientSecret, _skipTlsValidation = true) {
-        this._tokenEndpoint = _tokenEndpoint;
-        this._clientId = _clientId;
-        this._clientSecret = _clientSecret;
-        this._skipTlsValidation = _skipTlsValidation;
+    /**
+     * Creates a new {@link OAuthTokenProvider}.
+     * @param tokenEndpoint - The OAuth2 token endpoint to request tokens from.
+     * @param clientId - The client identifier.
+     * @param clientSecret - The client secret.
+     * @param skipTlsValidation - Whether to skip TLS certificate chain validation.
+     * @param _fetchToken - Test-only seam replacing the OAuth2 token request.
+     */
+    constructor(tokenEndpoint, clientId, clientSecret, skipTlsValidation = true, _fetchToken = () => fetchOAuthAccessToken(tokenEndpoint, clientId, clientSecret, skipTlsValidation)) {
+        this._fetchToken = _fetchToken;
     }
     async getAccessToken() {
-        if (this._accessToken && new Date() < this._tokenExpiry) {
+        if (this.hasFreshToken()) {
             return this._accessToken;
         }
         if (this._refreshPromise) {
             return this._refreshPromise;
         }
-        this._refreshPromise = this.fetchAccessToken();
+        if (this.isThrottled()) {
+            return this.cachedTokenWhileValid();
+        }
+        this._refreshPromise = this.fetchAndCacheAccessToken();
         try {
             return await this._refreshPromise;
         }
@@ -49,56 +71,40 @@ export class OAuthTokenProvider {
     }
     async refresh() {
         this._accessToken = undefined;
-        this._tokenExpiry = new Date(0);
+        this._expiresAt = 0;
+        this._lastFailedFetch = undefined;
         return this.getAccessToken();
     }
-    async fetchAccessToken() {
-        const params = new URLSearchParams();
-        params.append('grant_type', 'client_credentials');
-        params.append('client_id', this._clientId);
-        params.append('client_secret', this._clientSecret);
-        const body = params.toString();
-        return new Promise((resolve, reject) => {
-            const url = new URL(this._tokenEndpoint);
-            const isHttps = url.protocol === 'https:';
-            const httpModule = isHttps ? https : http;
-            const req = httpModule.request(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded',
-                    'Content-Length': Buffer.byteLength(body)
-                },
-                // Chain validation is skipped only when skipTlsValidation is explicitly set,
-                // matching the gRPC channel's credentials for the same connection string.
-                ...(isHttps && this._skipTlsValidation ? { rejectUnauthorized: false } : {})
-            }, response => {
-                let data = '';
-                response.on('data', chunk => {
-                    data += chunk;
-                });
-                response.on('end', () => {
-                    if (response.statusCode !== 200) {
-                        reject(new Error(`Token request failed with status ${response.statusCode}: ${data}`));
-                        return;
-                    }
-                    try {
-                        const tokenResponse = JSON.parse(data);
-                        this._accessToken = tokenResponse.access_token;
-                        const expiresInSeconds = tokenResponse.expires_in || DEFAULT_TOKEN_EXPIRY_SECONDS;
-                        this._tokenExpiry = new Date(Date.now() + (expiresInSeconds - TOKEN_EXPIRY_BUFFER_SECONDS) * 1000);
-                        resolve(this._accessToken);
-                    }
-                    catch (error) {
-                        reject(new Error(`Failed to parse token response: ${error instanceof Error ? error.message : String(error)}`));
-                    }
-                });
-            });
-            req.on('error', error => {
-                reject(new Error(`Token request failed: ${error.message}`));
+    hasFreshToken() {
+        return !!this._accessToken && this._expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS;
+    }
+    isThrottled() {
+        return this._lastFailedFetch !== undefined && Date.now() - this._lastFailedFetch < FAILED_FETCH_RETRY_DELAY_MS;
+    }
+    cachedTokenWhileValid() {
+        return this._accessToken && Date.now() < this._expiresAt ? this._accessToken : undefined;
+    }
+    async fetchAndCacheAccessToken() {
+        try {
+            const response = await this._fetchToken();
+            this._accessToken = response.access_token;
+            this._expiresAt = Date.now() + this.lifetimeSecondsFrom(response) * 1000;
+            this._lastFailedFetch = undefined;
+            return this._accessToken;
+        }
+        catch (error) {
+            this._logger.warn('Failed to fetch OAuth2 token', {
+                error: error instanceof Error ? error.message : String(error)
             });
-            req.write(body);
-            req.end();
-        });
+            this._lastFailedFetch = Date.now();
+            return this.cachedTokenWhileValid();
+        }
+    }
+    // expires_in is RECOMMENDED but not required by OAuth2, and some servers send it
+    // as a string.
+    lifetimeSecondsFrom(response) {
+        const seconds = Number(response.expires_in);
+        return Number.isFinite(seconds) && seconds > 0 ? seconds : DEFAULT_TOKEN_EXPIRY_SECONDS;
     }
 }
 //# sourceMappingURL=TokenProvider.js.map

package/dist/connection/TokenProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"TokenProvider.js","sourceRoot":"","sources":["../../connection/TokenProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TokenProvider.js","sourceRoot":"","sources":["../../connection/TokenProvider.ts"],"names":[],"mappings":"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"}

package/dist/connection/fetchOAuthAccessToken.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The shape of a successful OAuth2 token response.
+ */
+export interface OAuthTokenResponse {
+    access_token: string;
+    /** RECOMMENDED but not required by OAuth2, and some servers send it as a string. */
+    expires_in?: number | string;
+}
+/**
+ * Requests an access token from an OAuth2 token endpoint using the client credentials flow.
+ * @param tokenEndpoint - The token endpoint URL.
+ * @param clientId - The client identifier.
+ * @param clientSecret - The client secret.
+ * @param skipTlsValidation - Whether to skip TLS certificate chain validation.
+ * @returns The parsed token response; rejects when the request fails or the response is not a valid token.
+ */
+export declare function fetchOAuthAccessToken(tokenEndpoint: string, clientId: string, clientSecret: string, skipTlsValidation: boolean): Promise<OAuthTokenResponse>;
+//# sourceMappingURL=fetchOAuthAccessToken.d.ts.map

package/dist/connection/fetchOAuthAccessToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchOAuthAccessToken.d.ts","sourceRoot":"","sources":["../../connection/fetchOAuthAccessToken.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACjC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,OAAO,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAwD7B"}

package/dist/connection/fetchOAuthAccessToken.js

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import * as http from 'http';
+import * as https from 'https';
+/**
+ * Requests an access token from an OAuth2 token endpoint using the client credentials flow.
+ * @param tokenEndpoint - The token endpoint URL.
+ * @param clientId - The client identifier.
+ * @param clientSecret - The client secret.
+ * @param skipTlsValidation - Whether to skip TLS certificate chain validation.
+ * @returns The parsed token response; rejects when the request fails or the response is not a valid token.
+ */
+export function fetchOAuthAccessToken(tokenEndpoint, clientId, clientSecret, skipTlsValidation) {
+    const params = new URLSearchParams();
+    params.append('grant_type', 'client_credentials');
+    params.append('client_id', clientId);
+    params.append('client_secret', clientSecret);
+    const body = params.toString();
+    return new Promise((resolve, reject) => {
+        const url = new URL(tokenEndpoint);
+        const isHttps = url.protocol === 'https:';
+        const httpModule = isHttps ? https : http;
+        const request = httpModule.request(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Length': Buffer.byteLength(body)
+            },
+            // Chain validation is skipped only when skipTlsValidation is explicitly set,
+            // matching the gRPC channel's credentials for the same connection string.
+            ...(isHttps && skipTlsValidation ? { rejectUnauthorized: false } : {})
+        }, response => {
+            let data = '';
+            response.on('data', chunk => {
+                data += chunk;
+            });
+            response.on('end', () => {
+                if (response.statusCode !== 200) {
+                    reject(new Error(`Token request failed with status ${response.statusCode}: ${data}`));
+                    return;
+                }
+                try {
+                    const tokenResponse = JSON.parse(data);
+                    if (!tokenResponse.access_token) {
+                        reject(new Error('Token response did not contain an access_token'));
+                        return;
+                    }
+                    resolve(tokenResponse);
+                }
+                catch (error) {
+                    reject(new Error(`Failed to parse token response: ${error instanceof Error ? error.message : String(error)}`));
+                }
+            });
+        });
+        request.on('error', error => {
+            reject(new Error(`Token request failed: ${error.message}`));
+        });
+        request.write(body);
+        request.end();
+    });
+}
+//# sourceMappingURL=fetchOAuthAccessToken.js.map

package/dist/connection/fetchOAuthAccessToken.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchOAuthAccessToken.js","sourceRoot":"","sources":["../../connection/fetchOAuthAccessToken.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAY/B;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACjC,aAAqB,EACrB,QAAgB,EAChB,YAAoB,EACpB,iBAA0B;IAE1B,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAAC;IAClD,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrC,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;IAE7C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAE/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC;QAC1C,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAE1C,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE;YACpC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACL,cAAc,EAAE,mCAAmC;gBACnD,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;aAC5C;YACD,6EAA6E;YAC7E,0EAA0E;YAC1E,GAAG,CAAC,OAAO,IAAI,iBAAiB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzE,EAAE,QAAQ,CAAC,EAAE;YACV,IAAI,IAAI,GAAG,EAAE,CAAC;YAEd,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE;gBACxB,IAAI,IAAI,KAAK,CAAC;YAClB,CAAC,CAAC,CAAC;YAEH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;gBACpB,IAAI,QAAQ,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;oBAC9B,MAAM,CAAC,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;oBACtF,OAAO;gBACX,CAAC;gBAED,IAAI,CAAC;oBACD,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;oBAC7D,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,CAAC;wBAC9B,MAAM,CAAC,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC,CAAC;wBACpE,OAAO;oBACX,CAAC;oBAED,OAAO,CAAC,aAAa,CAAC,CAAC;gBAC3B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACb,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;gBACnH,CAAC;YACL,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE;YACxB,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO,CAAC,GAAG,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../ChronicleClient.ts","../ChronicleOptions.ts","../EventStore.ts","../EventStoreName.ts","../EventStoreNamespaceName.ts","../IChronicleClient.ts","../IEventStore.ts","../Metrics.ts","../Tracing.ts","../index.ts","../artifacts/DefaultClientArtifactsProvider.ts","../artifacts/IClientArtifactsProvider.ts","../artifacts/index.ts","../auditing/Causation.ts","../auditing/CausationManager.ts","../auditing/CausationType.ts","../auditing/ICausationManager.ts","../auditing/index.ts","../compliance/ComplianceContracts.ts","../compliance/ComplianceMetadata.ts","../compliance/ComplianceMetadataResolver.ts","../compliance/ComplianceMetadataType.ts","../compliance/index.ts","../compliance/pii.ts","../connection/ChronicleConnection.ts","../connection/ChronicleConnectionString.ts","../connection/ChronicleServerAddressResolver.ts","../connection/ChronicleServices.ts","../connection/ChronicleSrvResolutionError.ts","../connection/ChronicleSrvResolver.ts","../connection/ConnectionLifecycle.ts","../connection/DateTimeOffset.ts","../connection/Guid.ts","../connection/ILoadBalancerStrategy.ts","../connection/KernelKeepAlive.ts","../connection/LeastConnectionsLoadBalancerStrategy.ts","../connection/LoadBalancerMode.ts","../connection/LoadBalancerStrategyFactory.ts","../connection/RandomLoadBalancerStrategy.ts","../connection/RoundRobinLoadBalancerStrategy.ts","../connection/TokenProvider.ts","../connection/formatServerAddress.ts","../connection/index.ts","../correlation/CorrelationId.ts","../correlation/CorrelationIdManager.ts","../correlation/ICorrelationIdAccessor.ts","../correlation/ICorrelationIdSetter.ts","../correlation/index.ts","../eventSequences/AppendError.ts","../eventSequences/AppendOptions.ts","../eventSequences/AppendResult.ts","../eventSequences/ConcurrencyScope.ts","../eventSequences/ConstraintViolation.ts","../eventSequences/EventForEventSourceId.ts","../eventSequences/EventLog.ts","../eventSequences/EventSequence.ts","../eventSequences/EventSequenceId.ts","../eventSequences/EventSequenceNumber.ts","../eventSequences/IEventLog.ts","../eventSequences/IEventSequence.ts","../eventSequences/ITransactionalEventSequence.ts","../eventSequences/TransactionalEventSequence.ts","../eventSequences/index.ts","../eventStoreSubscriptions/EventStoreSubscriptionBuilder.ts","../eventStoreSubscriptions/EventStoreSubscriptionDefinition.ts","../eventStoreSubscriptions/EventStoreSubscriptionId.ts","../eventStoreSubscriptions/EventStoreSubscriptions.ts","../eventStoreSubscriptions/IEventStoreSubscriptionBuilder.ts","../eventStoreSubscriptions/IEventStoreSubscriptions.ts","../eventStoreSubscriptions/contracts.ts","../eventStoreSubscriptions/index.ts","../events/AppendedEvent.ts","../events/CausationEntry.ts","../events/EventContext.ts","../events/EventType.ts","../events/EventTypeGeneration.ts","../events/EventTypeId.ts","../events/EventTypes.ts","../events/IEventTypes.ts","../events/eventTypeDecorator.ts","../events/index.ts","../events/constraints/ConstraintBuilder.ts","../events/constraints/ConstraintId.ts","../events/constraints/Constraints.ts","../events/constraints/IConstraint.ts","../events/constraints/IConstraintBuilder.ts","../events/constraints/IConstraints.ts","../events/constraints/IUniqueConstraintBuilder.ts","../events/constraints/UniqueConstraintBuilder.ts","../events/constraints/constraint.ts","../events/constraints/index.ts","../events/migrations/EventMigrationBuilder.ts","../events/migrations/EventMigrationPropertyBuilder.ts","../events/migrations/EventTypeMigrators.ts","../events/migrations/IEventMigrationBuilder.ts","../events/migrations/IEventMigrationPropertyBuilder.ts","../events/migrations/IEventTypeMigration.ts","../events/migrations/IEventTypeMigrators.ts","../events/migrations/InvalidMigrationGenerationGap.ts","../events/migrations/eventTypeMigration.ts","../events/migrations/index.ts","../identity/IIdentityProvider.ts","../identity/Identity.ts","../identity/IdentityProvider.ts","../identity/index.ts","../jobs/IJobs.ts","../jobs/JobId.ts","../jobs/Jobs.ts","../jobs/index.ts","../observation/ObserverId.ts","../observation/ObserverRunningState.ts","../observation/index.ts","../projections/IProjections.ts","../projections/ProjectionId.ts","../projections/Projections.ts","../projections/index.ts","../projections/declarative/AllSetBuilder.ts","../projections/declarative/FromBuilder.ts","../projections/declarative/FromEveryBuilder.ts","../projections/declarative/IAddBuilder.ts","../projections/declarative/IAddChildBuilder.ts","../projections/declarative/IAllSetBuilder.ts","../projections/declarative/IChildrenBuilder.ts","../projections/declarative/ICompositeKeyBuilder.ts","../projections/declarative/IFromBuilder.ts","../projections/declarative/IFromEveryBuilder.ts","../projections/declarative/IJoinBuilder.ts","../projections/declarative/INestedBuilder.ts","../projections/declarative/IProjectionBuilder.ts","../projections/declarative/IProjectionBuilderFor.ts","../projections/declarative/IProjectionFor.ts","../projections/declarative/IReadModelPropertiesBuilder.ts","../projections/declarative/IRemovedWithBuilder.ts","../projections/declarative/IRemovedWithJoinBuilder.ts","../projections/declarative/ISetBuilder.ts","../projections/declarative/ISubtractBuilder.ts","../projections/declarative/JoinBuilder.ts","../projections/declarative/ProjectionBuilderFor.ts","../projections/declarative/RemovedWithBuilder.ts","../projections/declarative/RemovedWithJoinBuilder.ts","../projections/declarative/SetBuilder.ts","../projections/declarative/index.ts","../projections/declarative/projection.ts","../projections/modelBound/FromEventMetadata.ts","../projections/modelBound/FromEventOptions.ts","../projections/modelBound/addFrom.ts","../projections/modelBound/childrenFrom.ts","../projections/modelBound/clearWith.ts","../projections/modelBound/count.ts","../projections/modelBound/decrement.ts","../projections/modelBound/fromEvent.ts","../projections/modelBound/fromEvery.ts","../projections/modelBound/increment.ts","../projections/modelBound/index.ts","../projections/modelBound/join.ts","../projections/modelBound/nested.ts","../projections/modelBound/notRewindable.ts","../projections/modelBound/passive.ts","../projections/modelBound/removedWith.ts","../projections/modelBound/removedWithJoin.ts","../projections/modelBound/setFrom.ts","../projections/modelBound/setFromContext.ts","../projections/modelBound/setValue.ts","../projections/modelBound/subtractFrom.ts","../reactors/IReactors.ts","../reactors/ReactorId.ts","../reactors/Reactors.ts","../reactors/index.ts","../reactors/reactor.ts","../readModels/IMaterializedReadModels.ts","../readModels/IReadModels.ts","../readModels/MaterializedReadModels.ts","../readModels/ReadModelChangeset.ts","../readModels/ReadModelId.ts","../readModels/ReadModelSnapshot.ts","../readModels/ReadModels.ts","../readModels/index.ts","../readModels/readModel.ts","../reducers/IReducers.ts","../reducers/ReducerId.ts","../reducers/Reducers.ts","../reducers/index.ts","../reducers/reducer.ts","../schemas/JsonSchema.ts","../schemas/JsonSchemaGenerator.ts","../schemas/index.ts","../schemas/jsonSchemaProperty.ts","../seeding/EventSeeding.ts","../seeding/ICanSeedEvents.ts","../seeding/IEventSeeding.ts","../seeding/IEventSeedingBuilder.ts","../seeding/IEventSeedingScopeBuilder.ts","../seeding/index.ts","../seeding/seeder.ts","../sinks/WellKnownSinks.ts","../sinks/index.ts","../transactions/IUnitOfWork.ts","../transactions/IUnitOfWorkManager.ts","../transactions/NoUnitOfWorkHasBeenStarted.ts","../transactions/UnitOfWork.ts","../transactions/UnitOfWorkManager.ts","../transactions/index.ts","../types/DecoratorType.ts","../types/TypeDiscoverer.ts","../types/TypeIntrospector.ts","../types/index.ts","../webhooks/IWebhook.ts","../webhooks/IWebhookDefinitionBuilder.ts","../webhooks/IWebhooks.ts","../webhooks/WebhookDefinitionBuilder.ts","../webhooks/WebhookId.ts","../webhooks/WebhookTargetUrl.ts","../webhooks/Webhooks.ts","../webhooks/index.ts","../webhooks/webhook.ts"],"version":"6.0.3"}
+{"root":["../ChronicleClient.ts","../ChronicleOptions.ts","../EventStore.ts","../EventStoreName.ts","../EventStoreNamespaceName.ts","../IChronicleClient.ts","../IEventStore.ts","../Metrics.ts","../Tracing.ts","../index.ts","../artifacts/DefaultClientArtifactsProvider.ts","../artifacts/IClientArtifactsProvider.ts","../artifacts/index.ts","../auditing/Causation.ts","../auditing/CausationManager.ts","../auditing/CausationType.ts","../auditing/ICausationManager.ts","../auditing/index.ts","../compliance/ComplianceContracts.ts","../compliance/ComplianceMetadata.ts","../compliance/ComplianceMetadataResolver.ts","../compliance/ComplianceMetadataType.ts","../compliance/index.ts","../compliance/pii.ts","../connection/ChronicleConnection.ts","../connection/ChronicleConnectionString.ts","../connection/ChronicleServerAddressResolver.ts","../connection/ChronicleServices.ts","../connection/ChronicleSrvResolutionError.ts","../connection/ChronicleSrvResolver.ts","../connection/ConnectionLifecycle.ts","../connection/DateTimeOffset.ts","../connection/Guid.ts","../connection/ILoadBalancerStrategy.ts","../connection/KernelKeepAlive.ts","../connection/LeastConnectionsLoadBalancerStrategy.ts","../connection/LoadBalancerMode.ts","../connection/LoadBalancerStrategyFactory.ts","../connection/RandomLoadBalancerStrategy.ts","../connection/RoundRobinLoadBalancerStrategy.ts","../connection/TokenProvider.ts","../connection/fetchOAuthAccessToken.ts","../connection/formatServerAddress.ts","../connection/index.ts","../correlation/CorrelationId.ts","../correlation/CorrelationIdManager.ts","../correlation/ICorrelationIdAccessor.ts","../correlation/ICorrelationIdSetter.ts","../correlation/index.ts","../eventSequences/AppendError.ts","../eventSequences/AppendOptions.ts","../eventSequences/AppendResult.ts","../eventSequences/ConcurrencyScope.ts","../eventSequences/ConstraintViolation.ts","../eventSequences/EventForEventSourceId.ts","../eventSequences/EventLog.ts","../eventSequences/EventSequence.ts","../eventSequences/EventSequenceId.ts","../eventSequences/EventSequenceNumber.ts","../eventSequences/IEventLog.ts","../eventSequences/IEventSequence.ts","../eventSequences/ITransactionalEventSequence.ts","../eventSequences/TransactionalEventSequence.ts","../eventSequences/index.ts","../eventStoreSubscriptions/EventStoreSubscriptionBuilder.ts","../eventStoreSubscriptions/EventStoreSubscriptionDefinition.ts","../eventStoreSubscriptions/EventStoreSubscriptionId.ts","../eventStoreSubscriptions/EventStoreSubscriptions.ts","../eventStoreSubscriptions/IEventStoreSubscriptionBuilder.ts","../eventStoreSubscriptions/IEventStoreSubscriptions.ts","../eventStoreSubscriptions/contracts.ts","../eventStoreSubscriptions/index.ts","../events/AppendedEvent.ts","../events/CausationEntry.ts","../events/EventContext.ts","../events/EventType.ts","../events/EventTypeGeneration.ts","../events/EventTypeId.ts","../events/EventTypes.ts","../events/IEventTypes.ts","../events/eventTypeDecorator.ts","../events/index.ts","../events/constraints/ConstraintBuilder.ts","../events/constraints/ConstraintId.ts","../events/constraints/Constraints.ts","../events/constraints/IConstraint.ts","../events/constraints/IConstraintBuilder.ts","../events/constraints/IConstraints.ts","../events/constraints/IUniqueConstraintBuilder.ts","../events/constraints/UniqueConstraintBuilder.ts","../events/constraints/constraint.ts","../events/constraints/index.ts","../events/migrations/EventMigrationBuilder.ts","../events/migrations/EventMigrationPropertyBuilder.ts","../events/migrations/EventTypeMigrators.ts","../events/migrations/IEventMigrationBuilder.ts","../events/migrations/IEventMigrationPropertyBuilder.ts","../events/migrations/IEventTypeMigration.ts","../events/migrations/IEventTypeMigrators.ts","../events/migrations/InvalidMigrationGenerationGap.ts","../events/migrations/eventTypeMigration.ts","../events/migrations/index.ts","../identity/IIdentityProvider.ts","../identity/Identity.ts","../identity/IdentityProvider.ts","../identity/index.ts","../jobs/IJobs.ts","../jobs/JobId.ts","../jobs/Jobs.ts","../jobs/index.ts","../observation/ObserverId.ts","../observation/ObserverRunningState.ts","../observation/index.ts","../projections/IProjections.ts","../projections/ProjectionId.ts","../projections/Projections.ts","../projections/index.ts","../projections/declarative/AllSetBuilder.ts","../projections/declarative/FromBuilder.ts","../projections/declarative/FromEveryBuilder.ts","../projections/declarative/IAddBuilder.ts","../projections/declarative/IAddChildBuilder.ts","../projections/declarative/IAllSetBuilder.ts","../projections/declarative/IChildrenBuilder.ts","../projections/declarative/ICompositeKeyBuilder.ts","../projections/declarative/IFromBuilder.ts","../projections/declarative/IFromEveryBuilder.ts","../projections/declarative/IJoinBuilder.ts","../projections/declarative/INestedBuilder.ts","../projections/declarative/IProjectionBuilder.ts","../projections/declarative/IProjectionBuilderFor.ts","../projections/declarative/IProjectionFor.ts","../projections/declarative/IReadModelPropertiesBuilder.ts","../projections/declarative/IRemovedWithBuilder.ts","../projections/declarative/IRemovedWithJoinBuilder.ts","../projections/declarative/ISetBuilder.ts","../projections/declarative/ISubtractBuilder.ts","../projections/declarative/JoinBuilder.ts","../projections/declarative/ProjectionBuilderFor.ts","../projections/declarative/RemovedWithBuilder.ts","../projections/declarative/RemovedWithJoinBuilder.ts","../projections/declarative/SetBuilder.ts","../projections/declarative/index.ts","../projections/declarative/projection.ts","../projections/modelBound/FromEventMetadata.ts","../projections/modelBound/FromEventOptions.ts","../projections/modelBound/addFrom.ts","../projections/modelBound/childrenFrom.ts","../projections/modelBound/clearWith.ts","../projections/modelBound/count.ts","../projections/modelBound/decrement.ts","../projections/modelBound/fromEvent.ts","../projections/modelBound/fromEvery.ts","../projections/modelBound/increment.ts","../projections/modelBound/index.ts","../projections/modelBound/join.ts","../projections/modelBound/nested.ts","../projections/modelBound/notRewindable.ts","../projections/modelBound/passive.ts","../projections/modelBound/removedWith.ts","../projections/modelBound/removedWithJoin.ts","../projections/modelBound/setFrom.ts","../projections/modelBound/setFromContext.ts","../projections/modelBound/setValue.ts","../projections/modelBound/subtractFrom.ts","../reactors/IReactors.ts","../reactors/ReactorId.ts","../reactors/Reactors.ts","../reactors/index.ts","../reactors/reactor.ts","../readModels/IMaterializedReadModels.ts","../readModels/IReadModels.ts","../readModels/MaterializedReadModels.ts","../readModels/ReadModelChangeset.ts","../readModels/ReadModelId.ts","../readModels/ReadModelSnapshot.ts","../readModels/ReadModels.ts","../readModels/index.ts","../readModels/readModel.ts","../reducers/IReducers.ts","../reducers/ReducerId.ts","../reducers/Reducers.ts","../reducers/index.ts","../reducers/reducer.ts","../schemas/JsonSchema.ts","../schemas/JsonSchemaGenerator.ts","../schemas/index.ts","../schemas/jsonSchemaProperty.ts","../seeding/EventSeeding.ts","../seeding/ICanSeedEvents.ts","../seeding/IEventSeeding.ts","../seeding/IEventSeedingBuilder.ts","../seeding/IEventSeedingScopeBuilder.ts","../seeding/index.ts","../seeding/seeder.ts","../sinks/WellKnownSinks.ts","../sinks/index.ts","../transactions/IUnitOfWork.ts","../transactions/IUnitOfWorkManager.ts","../transactions/NoUnitOfWorkHasBeenStarted.ts","../transactions/UnitOfWork.ts","../transactions/UnitOfWorkManager.ts","../transactions/index.ts","../types/DecoratorType.ts","../types/TypeDiscoverer.ts","../types/TypeIntrospector.ts","../types/index.ts","../webhooks/IWebhook.ts","../webhooks/IWebhookDefinitionBuilder.ts","../webhooks/IWebhooks.ts","../webhooks/WebhookDefinitionBuilder.ts","../webhooks/WebhookId.ts","../webhooks/WebhookTargetUrl.ts","../webhooks/Webhooks.ts","../webhooks/index.ts","../webhooks/webhook.ts"],"version":"6.0.3"}

package/fundamentalsPeerRange.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+// The peer range's lower bound is a compatibility claim; the exact devDependency pin is the only version this
+// package is ever compiled and tested against. When they disagree the range claims support for versions nothing
+// verifies, and nothing fails until a consumer resolves one of them.
+//
+// That is not hypothetical: the range shipped as ^7 while ConceptAs - used here as a runtime value, compared by
+// class object in JsonSchemaGenerator - only exists from 7.14.0 onward, leaving 48 published versions that
+// satisfied the range and could not link. Tying the bound to the pin is what stops the two drifting again.
+const manifest = JSON.parse(
+    readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf-8')) as {
+        peerDependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+    };
+
+describe('fundamentals peer range', () => {
+    const peer = manifest.peerDependencies?.['@cratis/fundamentals'];
+    const pinned = manifest.devDependencies?.['@cratis/fundamentals'];
+
+    it('should declare fundamentals as a peer dependency', () => expect(peer).toBeDefined());
+
+    it('should pin one concrete version to build against', () => expect(pinned).toMatch(/^\d+\.\d+\.\d+$/));
+
+    it('should admit no version below the one it builds against', () => expect(peer).toBe(`^${pinned}`));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "2.1.0",
+    "version": "3.0.0",
     "description": "TypeScript idiomatic client for Cratis Chronicle",
     "author": "Cratis",
     "license": "MIT",
@@ -136,7 +136,6 @@
     "dependencies": {
         "@bufbuild/protobuf": "^2.12.0",
         "@cratis/chronicle.contracts": "16.4.0",
-        "@cratis/fundamentals": "7.14.0",
         "@grpc/grpc-js": "^1.14.4",
         "@opentelemetry/api": "^1.9.1",
         "nice-grpc": "^2.1.16",
@@ -145,8 +144,12 @@
         "undici": "^8.7.0"
     },
     "devDependencies": {
+        "@cratis/fundamentals": "7.14.0",
         "@types/node": "^25.9.1",
         "typescript": "^6.0.3",
         "vitest": "^4.1.10"
+    },
+    "peerDependencies": {
+        "@cratis/fundamentals": "^7.14.0"
     }
 }