From f83ac6d1c8515fb621f02551c509632257c22d6c Mon Sep 17 00:00:00 2001 From: Eugene Yakhnenko Date: Tue, 25 Aug 2026 12:13:18 -0700 Subject: [PATCH 1/4] docs(sdk): correct stale API comments Signed-off-by: Eugene Yakhnenko --- lib/src/access.ts | 7 +++---- lib/src/auth/providers.ts | 12 +++--------- lib/src/opentdf.ts | 16 +++++++++------- lib/tdf3/src/client/index.ts | 17 ++++++----------- 4 files changed, 21 insertions(+), 31 deletions(-) diff --git a/lib/src/access.ts b/lib/src/access.ts index 29cb2fb66..173606923 100644 --- a/lib/src/access.ts +++ b/lib/src/access.ts @@ -34,10 +34,9 @@ export type RewrapRequest = { /** * Get a rewrapped access key to the document, if possible * @param url Key access server rewrap endpoint - * @param requestBody a signed request with an encrypted document key - * @param authProvider Authorization middleware + * @param signedRequestToken Signed request token containing the encrypted document key. + * @param auth Connect interceptors or a legacy auth provider. * @param fulfillableObligationFQNs client-configured list of obligation value FQNs that can be fulfilled in this PEP - * @param clientVersion */ export async function fetchWrappedKey( url: string, @@ -209,7 +208,7 @@ export async function fetchECKasPubKey(kasEndpoint: string): Promise Promise; /** - * Mark this reader as closed and release any resources, such as open files. + * Marks the reader as closed. Does not release resources held by the source. */ close: () => Promise; @@ -256,8 +256,8 @@ export type TDFReader = { * The main OpenTDF class that provides methods for creating and reading TDF files. * It can be used to create new TDF files and read existing ones. * This class is the entry point for using the OpenTDF SDK. - * It requires an authentication provider to be passed in the constructor. - * It also requires a platform URL to be set, which is used to fetch key access servers and policies. + * Configure authentication with interceptors or the deprecated `authProvider`. + * Reads require a platform URL unless a KAS allowlist is supplied or allowlist checks are disabled. * @example * ``` * import { authTokenInterceptor, OpenTDF } from '@opentdf/sdk'; @@ -272,7 +272,9 @@ export type TDFReader = { * autoconfigure: false, * }); * - * const clearText = await client.read({ type: 'stream', location: cipherText }); + * const clearText = await client.read({ + * source: { type: 'stream', location: cipherText }, + * }); * ``` */ export class OpenTDF { @@ -411,7 +413,7 @@ export class OpenTDF { return reader.decrypt(); } - /** Closes the OpenTDF instance and releases any resources. */ + /** No-op retained for API compatibility. */ close() { // No-op for now, but kept for API compatibility } diff --git a/lib/tdf3/src/client/index.ts b/lib/tdf3/src/client/index.ts index 93099ed3c..8358897b4 100644 --- a/lib/tdf3/src/client/index.ts +++ b/lib/tdf3/src/client/index.ts @@ -336,7 +336,7 @@ export class Client { /** * List of allowed KASes to connect to for rewrap requests. - * Defaults to `[this.kasEndpoint]`. + * If omitted, decrypt requires `platformUrl` and loads the platform allowlist. */ readonly allowedKases?: OriginAllowList; @@ -378,14 +378,9 @@ export class Client { readonly clientConfig: ClientConfig; /** - * An abstraction for protecting and accessing data using TDF3 services. - * @param {Object} [config.keypair] - keypair generated for signing. Optional, will be generated by sdk if not passed - * @param {String} [config.clientId] - * @param {String} [config.kasEndpoint] - Key Access Server url - * @param {String} [config.refreshToken] - After logging in to browser OIDC interface user - * receives fresh token that needed by SDK for auth needs - * @param {String} [config.externalJwt] - JWT from external authority (eg Google) - * @param {String} [config.oidcOrigin] - Endpoint of authentication service + * Creates a TDF3 client. Requires `kasEndpoint`. + * Configure authentication with `interceptors`, `authProvider`, or the legacy OIDC options. + * Generates signing keys when `dpopKeys` is omitted. */ constructor(config: ClientConfig) { const clientConfig = { ...defaultClientConfig, ...config }; @@ -517,7 +512,7 @@ export class Client { * @param [keyMiddleware] - function that handle keys * @param [streamMiddleware] - function that handle stream * @param [eo] - (deprecated) entity object - * @return a {@link https://nodejs.org/api/stream.html#stream_class_stream_readable|Readable} a new stream containing the TDF ciphertext + * @returns A decorated stream whose Web ReadableStream contains the TDF ciphertext. */ async encrypt(opts: EncryptParams): Promise { if (opts.offline === false) { @@ -791,7 +786,7 @@ export class Client { * @param params.eo Optional entity object (legacy AuthZ) * @param params.assertionVerificationKeys Optional verification keys for assertions. * @param params.fulfillableObligationFQNs Optional fulfillable obligation value FQNs (overrides those on the Client) - * @return a {@link https://nodejs.org/api/stream.html#stream_class_stream_readable|Readable} stream containing the decrypted plaintext. + * @returns A decorated stream whose Web ReadableStream contains the decrypted plaintext. * @see DecryptParamsBuilder */ async decrypt({ From cbbbac72992de34fe4479cd1a3581e42538bfc06 Mon Sep 17 00:00:00 2001 From: Eugene Yakhnenko Date: Tue, 25 Aug 2026 12:24:33 -0700 Subject: [PATCH 2/4] docs(sdk): clarify reader close behavior Signed-off-by: Eugene Yakhnenko --- lib/src/opentdf.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/src/opentdf.ts b/lib/src/opentdf.ts index cb67a18b5..1b75473bd 100644 --- a/lib/src/opentdf.ts +++ b/lib/src/opentdf.ts @@ -232,7 +232,7 @@ export type TDFReader = { */ decrypt: () => Promise; /** - * Marks the reader as closed. Does not release resources held by the source. + * Marks the internal reader state as closed. Currently performs no resource cleanup. */ close: () => Promise; From 6cf267c606436feffcbc48dafbda9aa493112e1f Mon Sep 17 00:00:00 2001 From: Eugene Yakhnenko Date: Tue, 25 Aug 2026 12:25:40 -0700 Subject: [PATCH 3/4] docs(sdk): describe reader close state Signed-off-by: Eugene Yakhnenko --- lib/src/opentdf.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/src/opentdf.ts b/lib/src/opentdf.ts index 1b75473bd..cc3c88282 100644 --- a/lib/src/opentdf.ts +++ b/lib/src/opentdf.ts @@ -232,7 +232,7 @@ export type TDFReader = { */ decrypt: () => Promise; /** - * Marks the internal reader state as closed. Currently performs no resource cleanup. + * Marks the internal reader state as closed. */ close: () => Promise; From 7db10f9f7e1c10b12b9ce570282f7316e7f7cf15 Mon Sep 17 00:00:00 2001 From: Eugene Yakhnenko Date: Tue, 25 Aug 2026 12:29:27 -0700 Subject: [PATCH 4/4] docs(sdk): restore TDF3 client config details Signed-off-by: Eugene Yakhnenko --- lib/tdf3/src/client/index.ts | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/lib/tdf3/src/client/index.ts b/lib/tdf3/src/client/index.ts index 8358897b4..757091955 100644 --- a/lib/tdf3/src/client/index.ts +++ b/lib/tdf3/src/client/index.ts @@ -128,11 +128,15 @@ const makeChunkable = async (source: DecryptSource) => { }; export interface ClientConfig { + /** Cryptographic implementation used by the client. */ cryptoService?: CryptoService; - /// oauth client id; used to generate oauth authProvider + /** OIDC client ID used by the legacy authentication flow. */ clientId?: string; + /** Enables DPoP for requests. */ dpopEnabled?: boolean; + /** Signing keys used for DPoP and signed request bodies. Generated when omitted. */ dpopKeys?: Promise; + /** Default Key Access Server URL. */ kasEndpoint: string; /** * Service to use to look up ABAC. Used during autoconfigure. Defaults to @@ -158,9 +162,12 @@ export interface ClientConfig { keyRewrapEndpoint?: string; // DEPRECATED Ignored keyUpsertEndpoint?: string; + /** Refresh token used by the legacy OIDC authentication flow. */ refreshToken?: string; kasPublicKey?: string; + /** Authentication service URL used by the legacy OIDC flow. */ oidcOrigin?: string; + /** External JWT used by the legacy token-exchange flow. */ externalJwt?: string; /** @deprecated since 0.14.0. Use `interceptors` instead. */ authProvider?: AuthProvider; @@ -378,9 +385,16 @@ export class Client { readonly clientConfig: ClientConfig; /** - * Creates a TDF3 client. Requires `kasEndpoint`. - * Configure authentication with `interceptors`, `authProvider`, or the legacy OIDC options. - * Generates signing keys when `dpopKeys` is omitted. + * An abstraction for protecting and accessing data using TDF3 services. + * @param config TDF3 client configuration. + * @param config.kasEndpoint Default Key Access Server URL. + * @param config.dpopKeys Signing keys used for DPoP and signed request bodies. Generated when omitted. + * @param config.interceptors Connect RPC authentication interceptors. + * @param config.authProvider Deprecated authentication provider. + * @param config.clientId OIDC client ID used by the legacy authentication flow. + * @param config.refreshToken Refresh token used by the legacy OIDC authentication flow. + * @param config.externalJwt External JWT used by the legacy token-exchange flow. + * @param config.oidcOrigin Authentication service URL used by the legacy OIDC flow. */ constructor(config: ClientConfig) { const clientConfig = { ...defaultClientConfig, ...config };