@opentdf/sdk 0.13.0-beta.122 → 0.13.0-beta.124

package/src/auth/interceptors.ts

@@ -0,0 +1,197 @@
+import { type Interceptor } from '@connectrpc/connect';
+export type { Interceptor } from '@connectrpc/connect';
+import { type CryptoService, type KeyPair } from '../../tdf3/src/crypto/declarations.js';
+import * as DefaultCryptoService from '../../tdf3/src/crypto/index.js';
+import DPoP from './dpop.js';
+import { type AuthProvider } from './auth.js';
+import { base64 } from '../encodings/index.js';
+
+/**
+ * A function that returns a valid access token string.
+ * Called per-request; implementations should handle caching/refresh internally.
+ */
+export type TokenProvider = () => Promise<string>;
+
+/**
+ * Options for creating a DPoP-aware auth interceptor.
+ */
+export type DPoPInterceptorOptions = {
+  /** Function that returns a valid access token (may cache/refresh internally). */
+  tokenProvider: TokenProvider;
+  /** DPoP signing key pair. If omitted, one is generated automatically. */
+  dpopKeys?: KeyPair | Promise<KeyPair>;
+  /** CryptoService for signing. Defaults to DefaultCryptoService. */
+  cryptoService?: CryptoService;
+};
+
+/**
+ * A DPoP interceptor that also exposes the resolved signing key pair.
+ * TDF encrypt/decrypt needs these keys for request body signing (reqSignature).
+ */
+export type DPoPInterceptor = Interceptor & {
+  /** The resolved DPoP key pair, for use in TDF request token signing. */
+  readonly dpopKeys: Promise<KeyPair>;
+};
+
+/**
+ * Creates a simple bearer-token interceptor.
+ * Calls `tokenProvider()` per-request and sets the `Authorization` header.
+ *
+ * @param tokenProvider Function returning a valid access token.
+ * @returns A Connect RPC Interceptor.
+ *
+ * @example
+ * ```ts
+ * const opentdf = new OpenTDF({
+ *   interceptors: [authTokenInterceptor(() => myAuth.getAccessToken())],
+ *   platformUrl: '/api',
+ * });
+ * ```
+ */
+export function authTokenInterceptor(tokenProvider: TokenProvider): Interceptor {
+  return (next) => async (req) => {
+    const token = await tokenProvider();
+    req.header.set('Authorization', `Bearer ${token}`);
+    return next(req);
+  };
+}
+
+/**
+ * Creates a DPoP-aware auth interceptor.
+ * Per-request: gets token, generates DPoP proof JWT, sets Authorization + DPoP + X-VirtruPubKey headers.
+ * Exposes `dpopKeys` for TDF request body signing.
+ *
+ * @param options DPoP interceptor configuration.
+ * @returns A DPoP interceptor with an exposed `dpopKeys` promise.
+ *
+ * @example
+ * ```ts
+ * const dpopInterceptor = authTokenDPoPInterceptor({
+ *   tokenProvider: () => myAuth.getAccessToken(),
+ * });
+ * const opentdf = new OpenTDF({
+ *   interceptors: [dpopInterceptor],
+ *   dpopKeys: dpopInterceptor.dpopKeys,
+ *   platformUrl: '/api',
+ * });
+ * ```
+ */
+export function authTokenDPoPInterceptor(options: DPoPInterceptorOptions): DPoPInterceptor {
+  const cryptoService = options.cryptoService ?? DefaultCryptoService;
+  const dpopKeysPromise: Promise<KeyPair> = options.dpopKeys
+    ? Promise.resolve(options.dpopKeys)
+    : cryptoService.generateSigningKeyPair();
+
+  const interceptor: Interceptor = (next) => async (req) => {
+    const [token, keys] = await Promise.all([options.tokenProvider(), dpopKeysPromise]);
+
+    const url = new URL(req.url);
+    const httpUri = `${url.origin}${url.pathname}`;
+
+    // Generate DPoP proof JWT for this request
+    const dpopProof = await DPoP(keys, cryptoService, httpUri, 'POST');
+
+    // Export public key PEM for X-VirtruPubKey header
+    const publicKeyPem = await cryptoService.exportPublicKeyPem(keys.publicKey);
+
+    req.header.set('Authorization', `Bearer ${token}`);
+    req.header.set('DPoP', dpopProof);
+    req.header.set('X-VirtruPubKey', base64.encode(publicKeyPem));
+
+    return next(req);
+  };
+
+  // Attach dpopKeys to the interceptor function
+  const dpopInterceptor = interceptor as DPoPInterceptor;
+  Object.defineProperty(dpopInterceptor, 'dpopKeys', {
+    value: dpopKeysPromise,
+    writable: false,
+    enumerable: true,
+  });
+
+  return dpopInterceptor;
+}
+
+/**
+ * Creates an interceptor that bridges an existing AuthProvider to the Interceptor pattern.
+ * Use this for backwards compatibility when migrating from AuthProvider to interceptors.
+ *
+ * @param authProvider The legacy AuthProvider to bridge.
+ * @returns A Connect RPC Interceptor.
+ */
+export function authProviderInterceptor(authProvider: AuthProvider): Interceptor {
+  return (next) => async (req) => {
+    const url = new URL(req.url);
+    const pathOnly = url.pathname;
+    // Signs only the path of the url in the request
+    let token;
+    try {
+      token = await authProvider.withCreds({
+        url: pathOnly,
+        method: 'POST',
+        // Start with any headers Connect already has
+        headers: {
+          ...Object.fromEntries(req.header.entries()),
+          'Content-Type': 'application/json',
+        },
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('public key') || msg.includes('updateClientPublicKey')) {
+        throw new Error(
+          'PlatformClient: DPoP key binding is not complete. ' +
+            'If you are using OpenTDF with PlatformClient, create OpenTDF first and ' +
+            '`await client.ready` before constructing PlatformClient. ' +
+            `Original error: ${msg}`
+        );
+      }
+      throw err;
+    }
+
+    Object.entries(token.headers).forEach(([key, value]) => {
+      req.header.set(key, value);
+    });
+
+    return await next(req);
+  };
+}
+
+/**
+ * Auth configuration: either a legacy AuthProvider or an object with interceptors.
+ */
+export type AuthConfig = AuthProvider | { interceptors: Interceptor[] };
+
+/**
+ * Type guard for AuthConfig with interceptors.
+ */
+export function isInterceptorConfig(auth: AuthConfig): auth is { interceptors: Interceptor[] } {
+  return 'interceptors' in auth && Array.isArray((auth as { interceptors: unknown }).interceptors);
+}
+
+/**
+ * Resolves an AuthConfig into interceptors for use with PlatformClient.
+ * If the config is an AuthProvider, it is bridged via authProviderInterceptor.
+ */
+export function resolveInterceptors(auth: AuthConfig): Interceptor[] {
+  if (isInterceptorConfig(auth)) {
+    return auth.interceptors;
+  }
+  return [authProviderInterceptor(auth)];
+}
+
+/**
+ * Resolves an AuthConfig into both interceptors and an optional AuthProvider.
+ * The AuthProvider is available for legacy code paths that need withCreds().
+ */
+export function resolveAuthConfig(auth: AuthConfig): {
+  interceptors: Interceptor[];
+  authProvider?: AuthProvider;
+} {
+  if (isInterceptorConfig(auth)) {
+    return { interceptors: auth.interceptors };
+  }
+  return {
+    interceptors: [authProviderInterceptor(auth)],
+    authProvider: auth,
+  };
+}

package/src/auth/token-providers.ts

@@ -0,0 +1,303 @@
+import { type TokenProvider } from './interceptors.js';
+import { ConfigurationError, TdfError } from '../errors.js';
+import { rstrip } from '../utils.js';
+
+/**
+ * Options for client credentials token provider.
+ *
+ * **Not for browser use.** Client secrets must not be exposed in client-side code.
+ * Use this only in server-side (Node.js/Deno) environments.
+ */
+export type ClientCredentialsTokenProviderOptions = {
+  /** OIDC client ID. */
+  clientId: string;
+  /** OIDC client secret. */
+  clientSecret: string;
+  /** OIDC IdP origin, e.g. 'http://localhost:8080/auth/realms/opentdf'. */
+  oidcOrigin: string;
+  /** Override the token endpoint (defaults to `${oidcOrigin}/protocol/openid-connect/token`). */
+  oidcTokenEndpoint?: string;
+};
+
+/**
+ * Options for refresh token provider.
+ */
+export type RefreshTokenProviderOptions = {
+  /** OIDC client ID. */
+  clientId: string;
+  /** Refresh token obtained from a prior login flow. */
+  refreshToken: string;
+  /** OIDC IdP origin, e.g. 'http://localhost:8080/auth/realms/opentdf'. */
+  oidcOrigin: string;
+  /** Override the token endpoint. */
+  oidcTokenEndpoint?: string;
+};
+
+/**
+ * Options for external JWT token provider (RFC 8693 token exchange).
+ */
+export type ExternalJwtTokenProviderOptions = {
+  /** OIDC client ID. */
+  clientId: string;
+  /** External JWT to exchange. */
+  externalJwt: string;
+  /** OIDC IdP origin, e.g. 'http://localhost:8080/auth/realms/opentdf'. */
+  oidcOrigin: string;
+  /** Override the token endpoint. */
+  oidcTokenEndpoint?: string;
+};
+
+type TokenResponse = {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+};
+
+function resolveTokenEndpoint(oidcOrigin: string, override?: string): string {
+  if (override?.trim()) return override;
+  const base = oidcOrigin?.trim();
+  if (!base) {
+    throw new ConfigurationError('oidcOrigin or oidcTokenEndpoint is required');
+  }
+  return `${rstrip(base, '/')}/protocol/openid-connect/token`;
+}
+
+/**
+ * Decode a JWT's exp claim without verifying the signature.
+ * Returns the expiration time in seconds since epoch, or undefined if not present.
+ */
+function getJwtExpiration(token: string): number | undefined {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return undefined;
+    // Base64url decode the payload
+    const payload = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    const padded = payload + '='.repeat((4 - (payload.length % 4)) % 4);
+    const decoded = JSON.parse(atob(padded));
+    return typeof decoded.exp === 'number' ? decoded.exp : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Compute the absolute expiry (seconds since epoch) for a token response.
+ * Prefers `expires_in` from the token response, falls back to the JWT `exp` claim.
+ */
+function resolveTokenExpiry(accessToken: string, expiresIn?: number): number | undefined {
+  if (typeof expiresIn === 'number') {
+    return Date.now() / 1000 + expiresIn;
+  }
+  return getJwtExpiration(accessToken);
+}
+
+function isTokenExpired(expiry: number | undefined, bufferSeconds = 30): boolean {
+  if (expiry === undefined) return true;
+  return Date.now() / 1000 >= expiry - bufferSeconds;
+}
+
+async function fetchToken(
+  tokenEndpoint: string,
+  body: Record<string, string>
+): Promise<TokenResponse> {
+  const response = await fetch(tokenEndpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams(body).toString(),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new TdfError(
+      `Token request failed: POST [${tokenEndpoint}] => ${response.status} ${response.statusText}: ${text}`
+    );
+  }
+  return (await response.json()) as TokenResponse;
+}
+
+/**
+ * Creates a TokenProvider that obtains tokens via the OAuth2 client credentials grant.
+ * Tokens are cached and automatically refreshed when expired.
+ *
+ * **Not for browser use.** Client secrets must not be exposed in client-side code.
+ * Use this only in server-side (Node.js/Deno) environments.
+ *
+ * @example
+ * ```ts
+ * const client = new OpenTDF({
+ *   interceptors: [authTokenInterceptor(clientCredentialsTokenProvider({
+ *     clientId: 'opentdf',
+ *     clientSecret: 'secret',
+ *     oidcOrigin: 'http://localhost:8080/auth/realms/opentdf',
+ *   }))],
+ *   platformUrl: 'http://localhost:8080',
+ * });
+ * ```
+ */
+export function clientCredentialsTokenProvider(
+  options: ClientCredentialsTokenProviderOptions
+): TokenProvider {
+  if (!options.clientId || !options.clientSecret) {
+    throw new ConfigurationError('clientId and clientSecret are required');
+  }
+  const tokenEndpoint = resolveTokenEndpoint(options.oidcOrigin, options.oidcTokenEndpoint);
+  let cachedToken: string | undefined;
+  let cachedExpiry: number | undefined;
+  let inFlight: Promise<string> | undefined;
+
+  return async () => {
+    if (cachedToken && !isTokenExpired(cachedExpiry)) {
+      return cachedToken;
+    }
+    if (!inFlight) {
+      inFlight = (async () => {
+        try {
+          const resp = await fetchToken(tokenEndpoint, {
+            grant_type: 'client_credentials',
+            client_id: options.clientId,
+            client_secret: options.clientSecret,
+          });
+          cachedToken = resp.access_token;
+          cachedExpiry = resolveTokenExpiry(resp.access_token, resp.expires_in);
+          return cachedToken;
+        } finally {
+          inFlight = undefined;
+        }
+      })();
+    }
+    return inFlight;
+  };
+}
+
+/**
+ * Creates a TokenProvider that uses a refresh token to obtain access tokens.
+ * On the first call, exchanges the refresh token. Subsequent calls use the
+ * latest refresh token from the IdP response.
+ *
+ * @example
+ * ```ts
+ * const client = new OpenTDF({
+ *   interceptors: [authTokenInterceptor(refreshTokenProvider({
+ *     clientId: 'my-app',
+ *     refreshToken: 'refresh-token-from-login',
+ *     oidcOrigin: 'http://localhost:8080/auth/realms/opentdf',
+ *   }))],
+ *   platformUrl: 'http://localhost:8080',
+ * });
+ * ```
+ */
+export function refreshTokenProvider(options: RefreshTokenProviderOptions): TokenProvider {
+  if (!options.clientId || !options.refreshToken) {
+    throw new ConfigurationError('clientId and refreshToken are required');
+  }
+  const tokenEndpoint = resolveTokenEndpoint(options.oidcOrigin, options.oidcTokenEndpoint);
+  let currentRefreshToken = options.refreshToken;
+  let cachedToken: string | undefined;
+  let cachedExpiry: number | undefined;
+  let inFlight: Promise<string> | undefined;
+
+  return async () => {
+    if (cachedToken && !isTokenExpired(cachedExpiry)) {
+      return cachedToken;
+    }
+    if (!inFlight) {
+      inFlight = (async () => {
+        try {
+          const resp = await fetchToken(tokenEndpoint, {
+            grant_type: 'refresh_token',
+            refresh_token: currentRefreshToken,
+            client_id: options.clientId,
+          });
+          cachedToken = resp.access_token;
+          cachedExpiry = resolveTokenExpiry(resp.access_token, resp.expires_in);
+          if (resp.refresh_token) {
+            currentRefreshToken = resp.refresh_token;
+          }
+          return cachedToken;
+        } finally {
+          inFlight = undefined;
+        }
+      })();
+    }
+    return inFlight;
+  };
+}
+
+/**
+ * Creates a TokenProvider that exchanges an external JWT for a platform token
+ * via RFC 8693 token exchange. After the initial exchange, uses the refresh
+ * token for subsequent calls.
+ *
+ * @example
+ * ```ts
+ * const client = new OpenTDF({
+ *   interceptors: [authTokenInterceptor(externalJwtTokenProvider({
+ *     clientId: 'my-app',
+ *     externalJwt: 'eyJhbGciOi...',
+ *     oidcOrigin: 'http://localhost:8080/auth/realms/opentdf',
+ *   }))],
+ *   platformUrl: 'http://localhost:8080',
+ * });
+ * ```
+ */
+export function externalJwtTokenProvider(options: ExternalJwtTokenProviderOptions): TokenProvider {
+  if (!options.clientId || !options.externalJwt) {
+    throw new ConfigurationError('clientId and externalJwt are required');
+  }
+  const tokenEndpoint = resolveTokenEndpoint(options.oidcOrigin, options.oidcTokenEndpoint);
+  let cachedToken: string | undefined;
+  let cachedExpiry: number | undefined;
+  let currentRefreshToken: string | undefined;
+  let initialExchangeDone = false;
+  let inFlight: Promise<string> | undefined;
+
+  return async () => {
+    if (cachedToken && !isTokenExpired(cachedExpiry)) {
+      return cachedToken;
+    }
+    if (!inFlight) {
+      inFlight = (async () => {
+        try {
+          let resp: TokenResponse;
+          if (!initialExchangeDone) {
+            resp = await fetchToken(tokenEndpoint, {
+              grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+              subject_token: options.externalJwt,
+              subject_token_type: 'urn:ietf:params:oauth:token-type:jwt',
+              audience: options.clientId,
+              client_id: options.clientId,
+            });
+            initialExchangeDone = true;
+          } else if (currentRefreshToken) {
+            resp = await fetchToken(tokenEndpoint, {
+              grant_type: 'refresh_token',
+              refresh_token: currentRefreshToken,
+              client_id: options.clientId,
+            });
+          } else {
+            // Re-exchange the original JWT if no refresh token available
+            resp = await fetchToken(tokenEndpoint, {
+              grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+              subject_token: options.externalJwt,
+              subject_token_type: 'urn:ietf:params:oauth:token-type:jwt',
+              audience: options.clientId,
+              client_id: options.clientId,
+            });
+          }
+
+          cachedToken = resp.access_token;
+          cachedExpiry = resolveTokenExpiry(resp.access_token, resp.expires_in);
+          if (resp.refresh_token) {
+            currentRefreshToken = resp.refresh_token;
+          }
+          return cachedToken;
+        } finally {
+          inFlight = undefined;
+        }
+      })();
+    }
+    return inFlight;
+  };
+}

package/src/index.ts

@@ -1,5 +1,23 @@
 export { type AuthProvider, type HttpMethod, HttpRequest, withHeaders } from './auth/auth.js';
 export * as AuthProviders from './auth/providers.js';
+export {
+  authTokenInterceptor,
+  authTokenDPoPInterceptor,
+  authProviderInterceptor,
+  type AuthConfig,
+  type DPoPInterceptor,
+  type DPoPInterceptorOptions,
+  type Interceptor,
+  type TokenProvider,
+} from './auth/interceptors.js';
+export {
+  clientCredentialsTokenProvider,
+  refreshTokenProvider,
+  externalJwtTokenProvider,
+  type ClientCredentialsTokenProviderOptions,
+  type RefreshTokenProviderOptions,
+  type ExternalJwtTokenProviderOptions,
+} from './auth/token-providers.js';
 export { attributeFQNsAsValues } from './policy/api.js';
 export {
   listAttributes,

package/src/opentdf.ts

@@ -1,4 +1,5 @@
 import { type AuthProvider } from './auth/providers.js';
+import { type Interceptor } from '@connectrpc/connect';
 import { ConfigurationError, InvalidFileError } from './errors.js';
 export { Client as TDF3Client } from '../tdf3/src/client/index.js';
 import { Chunker, fromSource, sourceToStream, type Source } from './seekable.js';
@@ -164,8 +165,17 @@ export type OpenTDFOptions = {
   /** Platform URL. */
   platformUrl?: string;
 
-  /** Auth provider for connections to the policy service and KASes. */
-  authProvider: AuthProvider;
+  /**
+   * Connect RPC interceptors for authentication. Preferred over authProvider.
+   * Use `authTokenInterceptor()` or `authTokenDPoPInterceptor()` to create interceptors.
+   */
+  interceptors?: Interceptor[];
+
+  /**
+   * Auth provider for connections to the policy service and KASes.
+   * @deprecated since 0.14.0. Use `interceptors` with `authTokenInterceptor()` or `authTokenDPoPInterceptor()` instead.
+   */
+  authProvider?: AuthProvider;
 
   /** Default settings for 'encrypt' type requests. */
   defaultCreateOptions?: Omit<CreateOptions, 'source'>;
@@ -236,18 +246,10 @@ export type TDFReader = {
  * It also requires a platform URL to be set, which is used to fetch key access servers and policies.
  * @example
  * ```
- * import { type Chunker, OpenTDF } from '@opentdf/sdk';
- *
- * const oidcCredentials: RefreshTokenCredentials = {
- *   clientId: keycloakClientId,
- *   exchange: 'refresh',
- *   refreshToken: refreshToken,
- *   oidcOrigin: keycloakUrl,
- * };
- * const authProvider = await AuthProviders.refreshAuthProvider(oidcCredentials);
+ * import { authTokenInterceptor, OpenTDF } from '@opentdf/sdk';
  *
  * const client = new OpenTDF({
- *   authProvider,
+ *   interceptors: [authTokenInterceptor(() => `${myAuth.token.accessToken}`)],
  *   platformUrl: 'https://platform.example.com',
  * });
  *
@@ -264,8 +266,10 @@ export class OpenTDF {
   readonly platformUrl: string;
   /** The policy service endpoint */
   readonly policyEndpoint: string;
-  /** The auth provider for the OpenTDF instance. */
-  readonly authProvider: AuthProvider;
+  /** The auth provider for the OpenTDF instance (deprecated, use interceptors). */
+  readonly authProvider?: AuthProvider;
+  /** Connect RPC interceptors for authentication. */
+  readonly interceptors?: Interceptor[];
   /** If DPoP is enabled for this instance. */
   readonly dpopEnabled: boolean;
   /** Default options for creating TDF objects. */
@@ -283,6 +287,7 @@ export class OpenTDF {
 
   constructor({
     authProvider,
+    interceptors,
     dpopKeys,
     defaultCreateOptions,
     defaultReadOptions,
@@ -291,7 +296,11 @@ export class OpenTDF {
     platformUrl,
     cryptoService,
   }: OpenTDFOptions) {
+    if (!authProvider && !interceptors?.length) {
+      throw new ConfigurationError('Either authProvider or interceptors must be provided.');
+    }
     this.authProvider = authProvider;
+    this.interceptors = interceptors;
     this.defaultCreateOptions = defaultCreateOptions || {};
     this.defaultReadOptions = defaultReadOptions || {};
     this.dpopEnabled = !disableDPoP;
@@ -308,6 +317,7 @@ export class OpenTDF {
     this.dpopKeys = dpopKeys ?? this.cryptoService.generateSigningKeyPair();
     this.tdf3Client = new TDF3Client({
       authProvider,
+      interceptors,
       dpopEnabled: this.dpopEnabled,
       dpopKeys: this.dpopEnabled ? this.dpopKeys : undefined,
       kasEndpoint: this.platformUrl || 'https://disallow.all.invalid',
@@ -315,21 +325,31 @@ export class OpenTDF {
       policyEndpoint,
       cryptoService: this.cryptoService,
     });
-    // Eagerly bind DPoP keys to the auth provider so PlatformClient
-    // can make gRPC calls without waiting for a TDF operation first.
-    // Note: TDF3Client.createSessionKeys() also calls updateClientPublicKey
-    // with the same keys, but the duplicate call is benign —
-    // refreshTokenClaimsWithClientPubkeyIfNeeded short-circuits when
-    // the signing key hasn't changed.
-    this.ready = this.dpopEnabled
-      ? this.dpopKeys.then((keys) => authProvider.updateClientPublicKey(keys))
-      : Promise.resolve();
-    // Prevent unhandled rejection if caller doesn't await ready.
-    // The error will still surface via TDF3Client's own key binding
-    // when encrypt/decrypt is called.
-    this.ready.catch((err) => {
-      console.warn('OpenTDF: DPoP key binding failed during initialization:', err);
-    });
+
+    if (interceptors?.length && !authProvider) {
+      // Interceptor path: no updateClientPublicKey needed.
+      // DPoP key binding is handled by the interceptor itself.
+      this.ready = Promise.resolve();
+    } else if (authProvider) {
+      // Legacy AuthProvider path: eagerly bind DPoP keys to the auth provider
+      // so PlatformClient can make gRPC calls without waiting for a TDF
+      // operation first.
+      // Note: TDF3Client.createSessionKeys() also calls updateClientPublicKey
+      // with the same keys, but the duplicate call is benign —
+      // refreshTokenClaimsWithClientPubkeyIfNeeded short-circuits when
+      // the signing key hasn't changed.
+      this.ready = this.dpopEnabled
+        ? this.dpopKeys.then((keys) => authProvider.updateClientPublicKey(keys))
+        : Promise.resolve();
+      // Prevent unhandled rejection if caller doesn't await ready.
+      // The error will still surface via TDF3Client's own key binding
+      // when encrypt/decrypt is called.
+      this.ready.catch((err) => {
+        console.warn('OpenTDF: DPoP key binding failed during initialization:', err);
+      });
+    } else {
+      this.ready = Promise.resolve();
+    }
   }
 
   /** Creates a new TDF stream. */
@@ -485,9 +505,9 @@ class ZTDFReader {
 
     const dpopKeys = await this.client.dpopKeys;
 
-    const { authProvider, cryptoService } = this.client;
-    if (!authProvider) {
-      throw new ConfigurationError('authProvider is required');
+    const { auth, cryptoService } = this.client;
+    if (!auth) {
+      throw new ConfigurationError('authProvider or interceptors are required');
     }
 
     let allowList: OriginAllowList | undefined;
@@ -498,14 +518,14 @@ class ZTDFReader {
         this.opts.ignoreAllowlist
       );
     } else if (this.opts.platformUrl) {
-      allowList = await fetchKeyAccessServers(this.opts.platformUrl, authProvider);
+      allowList = await fetchKeyAccessServers(this.opts.platformUrl, auth);
     }
 
     const overview = await this.overview;
     const oldStream = await decryptStreamFrom(
       {
         allowList,
-        authProvider,
+        auth,
         chunker: this.source,
         concurrencyLimit: 1,
         cryptoService,