@cratis/chronicle 6.9.1 → 6.10.0

package/ChronicleClient.ts

@@ -7,8 +7,11 @@ import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleOptions } from './ChronicleOptions.js';
 import { ChronicleConnection } from './connection/index.js';
 import { IncompatibleChronicleServer } from './connection/IncompatibleChronicleServer.js';
+import { OAuthTokenHttpError } from './connection/fetchOAuthAccessToken.js';
+import { RejectedChronicleCredentials } from './connection/RejectedChronicleCredentials.js';
 import { ensureCommandSuccess, ensureQuerySuccess } from './connection/callResults.js';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle.js';
+import { clientVersion } from './connection/clientVersion.js';
 import { KernelKeepAlive } from './connection/KernelKeepAlive.js';
 import { EventStore } from './EventStore.js';
 import { EventStoreName } from './EventStoreName.js';
@@ -52,6 +55,7 @@ export class ChronicleClient implements IChronicleClient {
     private _keepAliveAbortController?: AbortController;
     private _healthCheckInFlight = false;
     private _connectionFailure?: Error;
+    private _consecutiveCredentialRejections = 0;
 
     /**
      * Creates a new {@link ChronicleClient} using the provided options.
@@ -194,6 +198,7 @@ export class ChronicleClient implements IChronicleClient {
     /** @inheritdoc */
     dispose(): void {
         this._isDisposed = true;
+        for (const store of this._stores.values()) store.disposeObservations();
 
         if (this._watchdogHandle) {
             clearInterval(this._watchdogHandle);
@@ -232,6 +237,7 @@ export class ChronicleClient implements IChronicleClient {
                 // so this effectively waits until the channel reaches READY or fails.
                 await this._connection.server.getVersionInfo({}, { signal: AbortSignal.timeout(10_000) });
 
+                this._consecutiveCredentialRejections = 0;
                 this._logger.info('Connected to Chronicle kernel');
                 await this.startKernelKeepAlive();
                 await this._lifecycle.connected(error => {
@@ -243,9 +249,10 @@ export class ChronicleClient implements IChronicleClient {
 
 
             } catch (error) {
-                if (error instanceof IncompatibleChronicleServer) {
-                    this.failConnection(error);
-                    throw error;
+                const terminal = this.terminalConnectionError(error);
+                if (terminal) {
+                    this.failConnection(terminal);
+                    throw terminal;
                 }
                 attempt++;
                 const delayMs = await this.backOff(attempt, 'Connection attempt failed, retrying', error);
@@ -303,6 +310,7 @@ export class ChronicleClient implements IChronicleClient {
                         await this._connection.resetChannel();
                         await this._connection.connect();
                         await this._connection.server.getVersionInfo({}, { signal: AbortSignal.timeout(10_000) });
+                        this._consecutiveCredentialRejections = 0;
                         this._logger.info('Reconnected to Chronicle kernel', { attempt: attempt + 1 });
                         await this.startKernelKeepAlive();
                         await this._lifecycle.connected(connectedError => {
@@ -312,9 +320,10 @@ export class ChronicleClient implements IChronicleClient {
                         });
                         return;
                     } catch (reconnectError) {
-                        if (reconnectError instanceof IncompatibleChronicleServer) {
-                            this.failConnection(reconnectError);
-                            throw reconnectError;
+                        const terminal = this.terminalConnectionError(reconnectError);
+                        if (terminal) {
+                            this.failConnection(terminal);
+                            throw terminal;
                         }
                         attempt++;
                         await this.backOff(attempt, 'Reconnect attempt failed, retrying', reconnectError);
@@ -351,17 +360,49 @@ export class ChronicleClient implements IChronicleClient {
         try {
             return await action();
         } catch (error) {
-            if (!this.shouldReconnect(error)) {
-                throw error;
+            const terminal = this.terminalConnectionError(error);
+            if (terminal) {
+                this.failConnection(terminal);
+                throw terminal;
             }
+            if (!this.shouldReconnect(error)) throw error;
 
             await this.reconnect(operation, error);
-            return action();
+            try {
+                return await action();
+            } catch (retryError) {
+                const retryTerminal = this.terminalConnectionError(retryError);
+                if (retryTerminal) {
+                    this.failConnection(retryTerminal);
+                    throw retryTerminal;
+                }
+                throw retryError;
+            }
         }
     }
 
+    private terminalConnectionError(error: unknown): Error | undefined {
+        if (error instanceof IncompatibleChronicleServer || error instanceof RejectedChronicleCredentials) return error;
+        const rejection = (error as { code?: number })?.code === 16 &&
+            (this.options.connectionString.apiKey || this.hasOAuthCredentialRejection(error));
+        this._consecutiveCredentialRejections = rejection ? this._consecutiveCredentialRejections + 1 : 0;
+        if (this._consecutiveCredentialRejections === 3) {
+            return new RejectedChronicleCredentials(`Chronicle credentials were rejected: ${this.toErrorMessage(error)}`, { cause: error });
+        }
+        return undefined;
+    }
+
+    private hasOAuthCredentialRejection(error: unknown): boolean {
+        const tokenError = (error as { tokenFailure?: Error })?.tokenFailure;
+        const httpError = tokenError?.cause;
+        return httpError instanceof OAuthTokenHttpError && [400, 401].includes(httpError.statusCode) &&
+            ['invalid_client', 'unauthorized_client', 'invalid_grant'].includes(httpError.errorCode ?? '');
+    }
+
     private shouldReconnect(error: unknown): boolean {
-        if (error instanceof IncompatibleChronicleServer) return false;
+        if (error instanceof IncompatibleChronicleServer || error instanceof RejectedChronicleCredentials) return false;
+        if ((error as { code?: number })?.code === 16 &&
+            (this.options.connectionString.apiKey || !!(error as { tokenFailure?: Error })?.tokenFailure)) return true;
         const code = Number((error as { code?: number })?.code ?? -1);
         const details = String((error as { details?: string })?.details ?? '');
         const message = this.toErrorMessage(error);
@@ -439,9 +480,7 @@ export class ChronicleClient implements IChronicleClient {
         await keepAlive.start(
             {
                 ConnectionId: this._lifecycle.connectionId,
-                // TODO: Not derived from this package's own version anywhere yet; kept as
-                // the pre-existing hardcoded placeholder until such a mechanism exists.
-                ClientVersion: '1.0.0',
+                ClientVersion: clientVersion,
                 IsRunningWithDebugger: false,
                 ProcessId: process.pid,
                 ProcessPath: process.execPath,

package/ChronicleOptions.spec.ts

@@ -0,0 +1,54 @@
+// 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 } from 'vitest';
+import { ChronicleOptions } from './ChronicleOptions.js';
+
+const entry = process.argv[1];
+const execArgv = [...process.execArgv];
+const vitest = process.env.VITEST;
+const patterns = [
+    '**/*.ts', '**/*.tsx', '!**/*.d.ts', '!**/node_modules', '!**/dist', '!**/build',
+    '!**/.git', '!**/.vscode', '!**/*.spec.ts', '!**/*.test.ts', '!**/*.spec.tsx', '!**/*.test.tsx'
+];
+afterEach(() => {
+    process.argv[1] = entry;
+    process.execArgv = [...execArgv];
+    if (vitest === undefined) delete process.env.VITEST;
+    else process.env.VITEST = vitest;
+});
+
+describe('default artifact discovery', () => {
+    for (const extension of ['ts', 'tsx', 'mts', 'cts']) {
+        it(`scans TypeScript sources for a .${extension} entry`, () => {
+            process.argv[1] = `/app/index.${extension}`;
+            expect(ChronicleOptions.development().discoveryPatterns).toEqual(patterns);
+        });
+    }
+
+    it('scans a JavaScript entry under vitest', () => {
+        process.argv[1] = '/app/dist/index.js';
+        process.env.VITEST = 'true';
+        expect(ChronicleOptions.development().discoveryPatterns).toEqual(patterns);
+    });
+
+    it.each(['tsx', 'ts-node', '--experimental-strip-types', '--experimental-transform-types'])(
+        'scans a JavaScript entry with %s loader', loader => {
+            process.argv[1] = '/app/dist/index.js';
+            process.execArgv = [loader];
+            expect(ChronicleOptions.development().discoveryPatterns).toEqual(patterns);
+        });
+
+    it('does not scan files for a compiled JavaScript entry without a TypeScript runtime', () => {
+        process.argv[1] = '/app/dist/index.js';
+        delete process.env.VITEST;
+        process.execArgv = [];
+        expect(ChronicleOptions.development().discoveryPatterns).toEqual([]);
+    });
+
+    it('always honors explicit discovery patterns', () => {
+        process.argv[1] = '/app/dist/index.js';
+        const patterns = ['app/**/*.js', '!app/**/*.spec.js'];
+        expect(ChronicleOptions.development({ discoveryPatterns: patterns }).discoveryPatterns).toBe(patterns);
+    });
+});

package/ChronicleOptions.ts

@@ -56,7 +56,10 @@ export class ChronicleOptions {
     /**
      * Glob patterns used to discover artifact files at startup.
      * Patterns prefixed with '!' are treated as exclusions.
-     * Set to an empty array to disable automatic file discovery.
+     * By default, TypeScript entry files (.ts, .tsx, .mts, .cts) or TypeScript runtimes scan TypeScript sources;
+     * compiled JavaScript entry files do not scan (imported modules register their artifacts).
+     * Explicit patterns are used regardless of the entry file. Set to an empty array to
+     * disable automatic file discovery.
      */
     readonly discoveryPatterns: string[];
 
@@ -76,8 +79,20 @@ export class ChronicleOptions {
         this.softwareVersion = options.softwareVersion ?? '0.0.0';
         this.softwareCommit = options.softwareCommit ?? 'Unknown';
         this.clientArtifactsProvider = options.clientArtifactsProvider ?? DefaultClientArtifactsProvider.default;
-        this.discoveryPatterns = options.discoveryPatterns ?? [
+        this.discoveryPatterns = options.discoveryPatterns ?? ChronicleOptions.defaultDiscoveryPatterns();
+        this.defaultSinkTypeId = options.defaultSinkTypeId ?? WellKnownSinks.MongoDB;
+        this.reactorResultHandler = options.reactorResultHandler;
+    }
+
+    private static defaultDiscoveryPatterns(): string[] {
+        const typescriptEntry = /\.(?:ts|tsx|mts|cts)$/i.test(process.argv[1] ?? '');
+        const typescriptLoader = process.execArgv.some(arg => /(?:tsx|ts-node|--experimental-strip-types|--experimental-transform-types)/i.test(arg));
+        // process.features.typescript is set on every Node.js 24+ process (type stripping), so it
+        // does not mean the program was started from TypeScript; it is deliberately not consulted.
+        if (!typescriptEntry && !process.env.VITEST && !typescriptLoader) return [];
+        return [
             '**/*.ts',
+            '**/*.tsx',
             '!**/*.d.ts',
             '!**/node_modules',
             '!**/dist',
@@ -85,10 +100,10 @@ export class ChronicleOptions {
             '!**/.git',
             '!**/.vscode',
             '!**/*.spec.ts',
-            '!**/*.test.ts'
+            '!**/*.test.ts',
+            '!**/*.spec.tsx',
+            '!**/*.test.tsx'
         ];
-        this.defaultSinkTypeId = options.defaultSinkTypeId ?? WellKnownSinks.MongoDB;
-        this.reactorResultHandler = options.reactorResultHandler;
     }
 
     /**

package/EventStore.ts

@@ -101,7 +101,7 @@ export class EventStore implements IEventStore {
         this.projections = new Projections(name.value, namespace.value, _connection, artifacts, defaultSinkTypeId);
         this.reactors = new Reactors(artifacts, _connection, name.value, namespace.value, lifecycle, this.eventLog, reactorResultHandler);
         this.reducers = new Reducers(artifacts, _connection, name.value, namespace.value, lifecycle, defaultSinkTypeId);
-        this.readModels = new ReadModels(name.value, namespace.value, _connection, artifacts, defaultSinkTypeId);
+        this.readModels = new ReadModels(name.value, namespace.value, _connection, artifacts, defaultSinkTypeId, readModelType => this.projections.hasForModel(readModelType));
         this.jobs = new Jobs(name.value, namespace.value, _connection);
         this.webhooks = new Webhooks(name.value, _connection, this.eventTypes, artifacts);
         this.subscriptions = new EventStoreSubscriptions(this.eventTypes, name.value, _connection);
@@ -157,6 +157,12 @@ export class EventStore implements IEventStore {
         });
     }
 
+    /** Stops the store's long-lived observations when the client is disposed. */
+    disposeObservations(): void {
+        (this.reactors as Reactors).dispose();
+        (this.reducers as Reducers).dispose();
+    }
+
     /** @inheritdoc */
     getEventSequence(id: EventSequenceId): IEventSequence {
         const existing = this._sequences.get(id.value);

package/README.md

@@ -59,8 +59,7 @@ class EmployeeHired {
     }
 }
 
-// discoveryPatterns: [] relies on this module's imports instead of scanning source files.
-const client = new ChronicleClient(ChronicleOptions.development({ discoveryPatterns: [] }));
+const client = new ChronicleClient(ChronicleOptions.development());
 const store = await client.getEventStore('MyStore');
 const result = await store.eventLog.append('employee-123', new EmployeeHired('Jane', 'Doe'));
 console.log(`Appended at sequence number ${result.sequenceNumber.value}`);
@@ -73,7 +72,7 @@ Chronicle decorators work with both TC39 standard decorators (TypeScript 5.2+; d
 
 Read models are inferred from `@projection('id', Model)`, `@reducer('id', sequenceId, Model)`, or an exported model with `@fromEvent(Event)` or other model-bound property mappings. Their schema comes from the model type; the default identifier is its class name. See [read models](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/read-models.md) for preserving existing custom identifiers.
 
-`ChronicleOptions` scans `**/*.ts` files for artifacts by default, which needs the `glob` package, and fails when the matched `.ts` files cannot be loaded by Node.js. Import your artifact modules and pass `discoveryPatterns: []`, as in the example above, or see [artifact discovery](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/getting-started.md#artifact-discovery).
+Decorated artifacts register when their modules are imported. When the entry file is TypeScript (run through a loader such as `tsx`), the client also scans `**/*.ts` files by default; compiled JavaScript scans nothing unless you set `discoveryPatterns`. See [artifact discovery](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/getting-started.md#artifact-discovery).
 
 The client skips TLS certificate validation unless the connection string sets `skipTlsValidation=false`. Set it for every server other than a local development kernel; see [Connect to Chronicle](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/connecting.md).
 

package/artifacts/DefaultClientArtifactsProvider.ts

@@ -28,7 +28,10 @@ export class DefaultClientArtifactsProvider implements IClientArtifactsProvider
 
     /** @inheritdoc */
     get readModels(): Constructor[] {
-        const types = new Set(this.discoverer.getTypesByDecoratorType(DecoratorType.ReadModel));
+        const types = new Set([
+            ...this.discoverer.getTypesByDecoratorType(DecoratorType.ReadModel),
+            ...this.discoverer.getPropertyOnlyModels()
+        ]);
         for (const projection of this.projections) {
             const type = getProjectionMetadata(projection)?.readModelType;
             if (type) types.add(type);

package/connection/ChronicleConnection.auth.spec.ts

@@ -0,0 +1,219 @@
+// 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 { createServer, ServerError, type ServiceImplementation } from 'nice-grpc';
+import { ConnectionServiceDefinition, EventStoresDefinition, ServerDefinition } from '@cratis/chronicle.contracts';
+import { status } from '@grpc/grpc-js';
+import { ChronicleConnection } from './ChronicleConnection.js';
+import { ChronicleClient } from '../ChronicleClient.js';
+import { ChronicleOptions } from '../ChronicleOptions.js';
+import { OAuthTokenHttpError } from './fetchOAuthAccessToken.js';
+import { RejectedChronicleCredentials } from './RejectedChronicleCredentials.js';
+import { ClientError } from 'nice-grpc-common';
+
+const fetchToken = vi.hoisted(() => vi.fn());
+vi.mock('./fetchOAuthAccessToken.js', async importOriginal => ({ ...await importOriginal<typeof import('./fetchOAuthAccessToken.js')>(), fetchOAuthAccessToken: fetchToken }));
+vi.mock('./KernelKeepAlive.js', () => ({ KernelKeepAlive: class { async start() {} } }));
+
+const servers: Array<ReturnType<typeof createServer>> = [];
+const connections: ChronicleConnection[] = [];
+const clients: ChronicleClient[] = []; 
+
+async function listen(rejectAnonymous = false): Promise<number> {
+    const server = createServer();
+    const unsupported = async () => { throw new Error('Unexpected RPC'); };
+    const methods = Object.fromEntries(Object.keys(ConnectionServiceDefinition.methods).map(name => [name, unsupported]));
+    server.add(ConnectionServiceDefinition, {
+        ...methods, checkCompatibility: async () => {
+            if (rejectAnonymous) throw new ServerError(status.UNAUTHENTICATED, 'Unauthenticated');
+            return { IsCompatible: true, Incompatibilities: [], ServerVersion: 'test' };
+        }
+    } as ServiceImplementation<typeof ConnectionServiceDefinition>);
+    servers.push(server);
+    return server.listen('127.0.0.1:0');
+}
+
+async function listenAuthenticated(onCheck?: () => void): Promise<number> {
+    const server = createServer();
+    const authenticate = async (_request: unknown, context: { metadata: { get(key: string): string | undefined } }) => {
+        if (context.metadata.get('authorization') !== 'Bearer fresh' &&
+            context.metadata.get('api-key') !== 'valid') throw new ServerError(status.UNAUTHENTICATED, 'Unauthenticated');
+    };
+    const unsupported = async () => { throw new Error('Unexpected RPC'); };
+    server.add(ConnectionServiceDefinition, {
+        ...Object.fromEntries(Object.keys(ConnectionServiceDefinition.methods).map(name => [name, unsupported])),
+        checkCompatibility: async (request, context) => {
+            onCheck?.();
+            await authenticate(request, context);
+            return { IsCompatible: true, Incompatibilities: [], ServerVersion: 'test' };
+        }
+    } as ServiceImplementation<typeof ConnectionServiceDefinition>);
+    server.add(ServerDefinition, {
+        getVersionInfo: async () => ({}), resetKernelState: unsupported
+    } as ServiceImplementation<typeof ServerDefinition>);
+    server.add(EventStoresDefinition, {
+        allEventStores: async () => ({ IsAuthorized: true, Data: [] }),
+        ensureEventStore: unsupported, observeEventStores: unsupported
+    } as ServiceImplementation<typeof EventStoresDefinition>);
+    servers.push(server);
+    return server.listen('127.0.0.1:0');
+}
+
+afterEach(async () => {
+    for (const client of clients) client.dispose();
+    for (const connection of connections) connection.dispose();
+    for (const server of servers) await server.shutdown();
+    connections.length = 0;
+    clients.length = 0;
+    servers.length = 0;
+    fetchToken.mockReset();
+    vi.useRealTimers();
+});
+
+describe('ChronicleConnection authentication', () => {
+    it('uses the selected server for credentials and reuses a token when returning to that server', async () => {
+        const first = await listen();
+        const second = await listen();
+        fetchToken.mockImplementation(async (endpoint: string) => ({ access_token: endpoint, expires_in: 3600 }));
+        const connection = new ChronicleConnection({ connectionString: `chronicle://user:secret@127.0.0.1:${first},127.0.0.1:${second}?disableTls=true&loadBalancer=round-robin` });
+        connections.push(connection);
+
+        await connection.connect();
+        await connection.reconnect();
+        await connection.reconnect();
+
+        expect(fetchToken.mock.calls.map(call => call[0]).sort()).toEqual([
+            `http://127.0.0.1:${first}/connect/token`,
+            `http://127.0.0.1:${second}/connect/token`
+        ].sort());
+    });
+
+    it('keeps an explicit authority across server selections', async () => {
+        const first = await listen();
+        const second = await listen();
+        fetchToken.mockResolvedValue({ access_token: 'token', expires_in: 3600 });
+        const connection = new ChronicleConnection({
+            connectionString: `chronicle://user:secret@127.0.0.1:${first},127.0.0.1:${second}?disableTls=true&loadBalancer=round-robin`,
+            authority: 'http://identity.example:1234'
+        });
+        connections.push(connection);
+
+        await connection.connect();
+        await connection.reconnect();
+        expect(fetchToken).toHaveBeenCalledTimes(1);
+        expect(fetchToken.mock.calls[0][0]).toBe('http://identity.example:1234/connect/token');
+    });
+
+    it('includes the token endpoint failure when the unauthenticated RPC is rejected', async () => {
+        const port = await listen(true);
+        fetchToken.mockRejectedValue(new Error('invalid_client'));
+        const connection = new ChronicleConnection({ connectionString: `chronicle://wrong:wrong@127.0.0.1:${port}?disableTls=true` });
+        connections.push(connection);
+        await expect(connection.connect()).rejects.toThrow(`http://127.0.0.1:${port}/connect/token: invalid_client`);
+    });
+
+    it('preserves the gRPC code, path and original error on a token failure', async () => {
+        const port = await listen(true);
+        fetchToken.mockRejectedValue(new OAuthTokenHttpError(401, '{"error":"invalid_client"}'));
+        const connection = new ChronicleConnection({ connectionString: `chronicle://wrong:wrong@127.0.0.1:${port}?disableTls=true` });
+        connections.push(connection);
+        const error = await connection.connect().catch(error => error as ClientError);
+        expect(error).toBeInstanceOf(ClientError);
+        expect(error.code).toBe(status.UNAUTHENTICATED);
+        expect(error.path).toContain('CheckCompatibility');
+        expect(error.details).toContain('invalid_client');
+        expect(error.cause).toBeInstanceOf(ClientError);
+    });
+
+    it('refreshes a rejected cached token and retries one unary call', async () => {
+        const port = await listenAuthenticated();
+        fetchToken.mockResolvedValueOnce({ access_token: 'stale', expires_in: 3600 })
+            .mockResolvedValueOnce({ access_token: 'fresh', expires_in: 3600 });
+        const connection = new ChronicleConnection({ connectionString: `chronicle://user:secret@127.0.0.1:${port}?disableTls=true` });
+        connections.push(connection);
+        await expect(connection.connect()).resolves.toBeUndefined();
+        expect(fetchToken).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not retry streaming calls after an unauthenticated response', async () => {
+        const server = createServer();
+        const attempts = vi.fn();
+        const unsupported = async () => { throw new Error('Unexpected RPC'); };
+        server.add(ConnectionServiceDefinition, {
+            ...Object.fromEntries(Object.keys(ConnectionServiceDefinition.methods).map(name => [name, unsupported])),
+            checkCompatibility: async () => ({ IsCompatible: true, Incompatibilities: [], ServerVersion: 'test' }),
+            observeConnectedClients: async function* () {
+                attempts();
+                throw new ServerError(status.UNAUTHENTICATED, 'Token expired');
+            }
+        } as ServiceImplementation<typeof ConnectionServiceDefinition>);
+        servers.push(server);
+        const port = await server.listen('127.0.0.1:0');
+        fetchToken.mockResolvedValue({ access_token: 'stale', expires_in: 3600 });
+        const connection = new ChronicleConnection({ connectionString: `chronicle://user:secret@127.0.0.1:${port}?disableTls=true` });
+        connections.push(connection);
+        await connection.connect();
+        const observe = async () => { for await (const _ of connection.connections.observeConnectedClients({})) { /* drain */ } };
+        await expect(observe()).rejects.toMatchObject({ code: status.UNAUTHENTICATED });
+        expect(attempts).toHaveBeenCalledTimes(1);
+        expect(fetchToken).toHaveBeenCalledTimes(1);
+    });
+
+    it('connects after two startup invalid_client responses', async () => {
+        const port = await listenAuthenticated();
+        fetchToken.mockRejectedValueOnce(new OAuthTokenHttpError(401, '{"error":"invalid_client"}'))
+            .mockRejectedValueOnce(new OAuthTokenHttpError(401, '{"error":"invalid_client"}'))
+            .mockResolvedValue({ access_token: 'fresh', expires_in: 3600 });
+        const client = new ChronicleClient(ChronicleOptions.fromConnectionString(`chronicle://user:secret@127.0.0.1:${port}?disableTls=true`, { discoveryPatterns: [] }));
+        clients.push(client);
+        await expect(client.getEventStores()).resolves.toEqual([]);
+        expect(fetchToken).toHaveBeenCalledTimes(3);
+    }, 10000);
+
+    it('rejects persistent OAuth credential rejections after three connection attempts', async () => {
+        const port = await listenAuthenticated();
+        fetchToken.mockRejectedValue(new OAuthTokenHttpError(400, '{"error":"invalid_client"}'));
+        const client = new ChronicleClient(ChronicleOptions.fromConnectionString(`chronicle://user:secret@127.0.0.1:${port}?disableTls=true`, { discoveryPatterns: [] }));
+        clients.push(client);
+        await expect(client.getEventStores()).rejects.toBeInstanceOf(RejectedChronicleCredentials);
+        expect(fetchToken).toHaveBeenCalledTimes(3);
+    }, 10000);
+
+    it('keeps retrying proxy 403 responses without an OAuth error code', async () => {
+        const random = vi.spyOn(Math, 'random').mockReturnValue(0);
+        const checks = vi.fn();
+        const port = await listenAuthenticated(checks);
+        fetchToken.mockRejectedValue(new OAuthTokenHttpError(403, '<html>blocked</html>'));
+        const client = new ChronicleClient(ChronicleOptions.fromConnectionString(`chronicle://user:secret@127.0.0.1:${port}?disableTls=true`, { discoveryPatterns: [] }));
+        clients.push(client);
+        const pending = client.getEventStores().then(() => undefined, error => error as Error);
+        try {
+            await new Promise(resolve => setTimeout(resolve, 3900));
+            expect(checks.mock.calls.length).toBeGreaterThanOrEqual(4);
+            client.dispose();
+            expect((await pending).message).toMatch(/disposed/);
+        } finally {
+            random.mockRestore();
+        }
+    }, 15000);
+
+    it('rejects an API key after three unauthenticated kernel responses', async () => {
+        const checks = vi.fn();
+        const port = await listenAuthenticated(checks);
+        const client = new ChronicleClient(ChronicleOptions.fromConnectionString(`chronicle://127.0.0.1:${port}?disableTls=true&apiKey=wrong`, { discoveryPatterns: [] }));
+        clients.push(client);
+        await expect(client.getEventStores()).rejects.toBeInstanceOf(RejectedChronicleCredentials);
+        expect(checks).toHaveBeenCalledTimes(3);
+    }, 10000);
+
+    it('reports the selected endpoint and underlying failure for development credentials', async () => {
+        const port = await listen();
+        fetchToken.mockRejectedValue(new Error('ECONNREFUSED'));
+        const connection = new ChronicleConnection({ connectionString: `chronicle://127.0.0.1:${port}?disableTls=true` });
+        connections.push(connection);
+
+        await expect(connection.connect()).resolves.toBeUndefined();
+        expect(fetchToken.mock.calls[0][1]).toBe('chronicle-dev-client');
+    });
+});