feat(auth): add TokenManager for automated auth token lifecycle management

Introduces TokenManager and supporting classes to handle token acquisition, automatic
refresh, and updates via identity providers. This foundation enables consistent
authentication token management across different identity provider implementations.

Key additions:
- Add TokenManager to obtain and maintain auth tokens from identity providers with
  automated refresh scheduling based on TTL and configurable thresholds
- Add IdentityProvider interface for token acquisition from auth providers
- Implement Token class for managing token state and TTL tracking
- Include configurable retry mechanism with exponential backoff and jitter
- Add comprehensive test suite covering refresh cycles and error handling
- Add Clock abstraction and FakeClock for testing timing scenarios

This change establishes the core infrastructure needed for reliable token
lifecycle management across different authentication providers.

Author: bobymicroby

packages/client/lib/client/authx/clock.ts

@@ -0,0 +1,34 @@
+/**
+ * A clock that provides the current time in milliseconds since the epoch.
+ */
+export interface Clock {
+  // returns milliseconds since epoch
+  now(): number;
+}
+
+/**
+ * A clock that uses the system time ( Date.now() ) to provide the current time.
+ */
+export class SystemClock implements Clock {
+  now(): number {
+    return Date.now();
+  }
+}
+
+/**
+ * A fake clock that allows the time to be manually advanced.
+ */
+export class FakeClock implements Clock {
+  constructor(private timeMs: number) {}
+
+  now(): number {
+    return this.timeMs;
+  }
+
+  advance(ms: number): void {
+    this.timeMs += ms;
+  }
+}
+
+export const SYSTEM_CLOCK = new SystemClock();
+

packages/client/lib/client/authx/credentials-provider.ts

@@ -1,3 +1,5 @@
+import {Disposable} from './types';
+
 /**
  * Provides credentials asynchronously.
  */
@@ -66,12 +68,6 @@ export type StreamingCredentialsListener<T> = {
   onError: (e: Error) => void;
 }
 
-/**
- * Disposable is an interface for objects that hold resources that should be released when they are no longer needed.
- */
-export type Disposable = {
-  dispose: () => void;
-}
 
 /**
  * Providers that can supply authentication credentials

packages/client/lib/client/authx/identity-provider.ts

@@ -0,0 +1,22 @@
+/**
+ * An identity provider is responsible for providing a token that can be used to authenticate with a service.
+ */
+
+/**
+ * The response from an identity provider when requesting a token.
+ *
+ * note: "native" refers to the type of the token that the actual identity provider library is using.
+ *
+ * @type T The type of the native idp token.
+ * @property token The token.
+ * @property ttlMs The time-to-live of the token in epoch milliseconds extracted from the native token in local time.
+ */
+export type TokenResponse<T> = { token: T, ttlMs: number };
+
+export interface IdentityProvider<T> {
+  /**
+   * Request a token from the identity provider.
+   * @returns A promise that resolves to an object containing the token and the time-to-live in epoch milliseconds.
+   */
+  requestToken(): Promise<TokenResponse<T>>;
+}