@opentdf/sdk 0.4.0-beta.19 → 0.4.0-beta.4

package/src/opentdf.ts

@@ -50,175 +50,162 @@ export {
   isPublicKeyAlgorithm,
 };
 
-/** A map of key identifiers to cryptographic keys. */
 export type Keys = {
   [keyID: string]: CryptoKey | CryptoKeyPair;
 };
 
-/** Options for creating a new TDF object, shared between all container types. */
+// Options when creating a new TDF object
+// that are shared between all container types.
 export type CreateOptions = {
-  /** If the policy service should be used to control creation options. */
+  // If the policy service should be used to control creation options
   autoconfigure?: boolean;
 
-  /** List of attributes that will be assigned to the object's policy. */
+  // List of attributes that will be assigned to the object's policy
   attributes?: string[];
 
-  /**
-   * If set and positive, this represents the maxiumum number of bytes to read from a stream to encrypt.
-   * This is helpful for enforcing size limits and preventing DoS attacks.
-   */
+  // If set and positive, this represents the maxiumum number of bytes to read from a stream to encrypt.
+  // This is helpful for enforcing size limits and preventing DoS attacks.
   byteLimit?: number;
 
-  /** The KAS to use for creation, if none is specified by the attribute service. */
+  // The KAS to use for creation, if none is specified by the attribute service.
   defaultKASEndpoint?: string;
 
-  /** Private (or shared) keys for signing assertions and bindings. */
+  // Private (or shared) keys for signing assertions and bindings
   signers?: Keys;
 
-  /** Source of plaintext data. */
+  // Source of plaintext data
   source: Source;
 };
 
-/** Options for creating a NanoTDF. */
 export type CreateNanoTDFOptions = CreateOptions & {
-  /** The type of binding to use for the NanoTDF. */
   bindingType?: 'ecdsa' | 'gmac';
 
-  /** When creating a new collection, use ECDSA binding with this key id from the signers, instead of the DEK. */
+  // When creating a new collection, use ECDSA binding with this key id from the signers,
+  // instead of the DEK.
   ecdsaBindingKeyID?: string;
 
-  /**
-   * When creating a new collection, use the key in the `signers` list with this id
-   * to generate a signature for each element. When absent, the nanotdf is unsigned.
-   */
+  // When creating a new collection,
+  // use the key in the `signers` list with this id
+  // to generate a signature for each element.
+  // When absent, the nanotdf is unsigned.
   signingKeyID?: string;
 };
 
-/** Options for creating a NanoTDF collection. */
 export type CreateNanoTDFCollectionOptions = CreateNanoTDFOptions & {
-  /** The platform URL. */
   platformUrl: string;
-  /** The maximum number of key iterations to use for a single DEK. */
+  // The maximum number of key iterations to use for a single DEK.
   maxKeyIterations?: number;
 };
 
-/** Metadata for a TDF object. */
+// Metadata for a TDF object.
 export type Metadata = object;
 
-/** MIME type of the decrypted content. */
+// MIME type of the decrypted content.
 export type MimeType = `${string}/${string}`;
 
-/** Template for a Key Access Object (KAO) to be filled in during encrypt. */
+// Template for a Key Access Object (KAO) to be filled in during encrypt.
 export type SplitStep = {
-  /** Which KAS to use to rewrap this segment of the key. */
+  // Which KAS to use to rewrap this segment of the key
   kas: string;
 
-  /**
-   * An identifier for a key segment.
-   * Leave empty to share the key.
-   */
+  // An identifier for a key segment.
+  // Leave empty to share the key.
   sid?: string;
 };
 
-/** Options specific to the ZTDF container format. */
+/// Options specific to the ZTDF container format.
 export type CreateZTDFOptions = CreateOptions & {
-  /** Configuration for bound metadata. */
+  // Configuration for bound metadata.
   assertionConfigs?: AssertionConfig[];
 
-  /** Unbound metadata (deprecated). */
+  // Unbound metadata (deprecated)
   metadata?: Metadata;
 
-  /** MIME type of the decrypted content. Used for display. */
+  // MIME type of the decrypted content. Used for display.
   mimeType?: MimeType;
 
-  /** How to split or share the data encryption key across multiple KASes. */
+  // How to split or share the data encryption key across multiple KASes.
   splitPlan?: SplitStep[];
 
-  /**
-   * The segment size for the content; smaller is slower, but allows faster random access.
-   * The current default is 1 MiB (2^20 bytes).
-   */
+  // The segment size for the content; smaller is slower, but allows faster random access.
+  // The current default is 1 MiB (2^20 bytes).
   windowSize?: number;
 
-  /** Preferred algorithm to use for Key Access Objects. */
+  // Preferred algorithm to use for Key Access Objects.
   wrappingKeyAlgorithm?: KasPublicKeyAlgorithm;
 
-  /** TDF spec version to target. */
+  // TDF spec version to target
   tdfSpecVersion?: '4.2.2' | '4.3.0';
 };
 
-/** Settings for decrypting any variety of TDF file. */
+// Settings for decrypting any variety of TDF file.
 export type ReadOptions = {
-  /** The ciphertext source. */
+  // ciphertext
   source: Source;
-  /** The platform URL. */
+  // Platform URL
   platformUrl?: string;
-  /** List of KASes that may be contacted for a rewrap. */
+  // list of KASes that may be contacted for a rewrap
   allowedKASEndpoints?: string[];
-  /** Optionally disable checking the allowlist. */
+  // Optionally disable checking the allowlist
   ignoreAllowlist?: boolean;
-  /** Public (or shared) keys for verifying assertions. */
+  // Public (or shared) keys for verifying assertions
   assertionVerificationKeys?: AssertionVerificationKeys;
-  /** Optionally disable assertion verification. */
+  // Optionally disable assertion verification
   noVerify?: boolean;
 
-  /** If set, prevents more than this number of concurrent requests to the KAS. */
+  // If set, prevents more than this number of concurrent requests to the KAS.
   concurrencyLimit?: number;
 
-  /** Type of key to use for wrapping responses. */
+  // Type of key to use for wrapping responses.
   wrappingKeyAlgorithm?: KasPublicKeyAlgorithm;
 };
 
-/** Defaults and shared settings that are relevant to creating TDF objects. */
+// Defaults and shared settings that are relevant to creating TDF objects.
 export type OpenTDFOptions = {
-  /** Policy service endpoint. */
+  // Policy service endpoint
   policyEndpoint?: string;
 
-  /** Platform URL. */
+  // Platform URL
   platformUrl?: string;
 
-  /** Auth provider for connections to the policy service and KASes. */
+  // Auth provider for connections to the policy service and KASes.
   authProvider: AuthProvider;
 
-  /** Default settings for 'encrypt' type requests. */
+  // Default settings for 'encrypt' type requests.
   defaultCreateOptions?: Omit<CreateOptions, 'source'>;
 
-  /** Default settings for 'decrypt' type requests. */
+  // Default settings for 'decrypt' type requests.
   defaultReadOptions?: Omit<ReadOptions, 'source'>;
 
-  /** If we want to *not* send a DPoP token. */
+  // If we want to *not* send a DPoP token
   disableDPoP?: boolean;
 
-  /**
-   * Optional keys for DPoP requests to a server.
-   * These often must be registered via a DPoP flow with the IdP
-   * which is out of the scope of this library.
-   */
+  // Optional keys for DPoP requests to a server.
+  // These often must be registered via a DPoP flow with the IdP
+  // which is out of the scope of this library.
   dpopKeys?: Promise<CryptoKeyPair>;
 
-  /** Configuration options for the collection header cache. */
+  // Configuration options for the collection header cache.
   rewrapCacheOptions?: RewrapCacheOptions;
 };
 
-/** A decorated readable stream. */
 export type DecoratedStream = ReadableStream<Uint8Array> & {
-  /** If the source is a TDF3/ZTDF, and includes metadata, and it has been read. */
+  // If the source is a TDF3/ZTDF, and includes metadata, and it has been read.
   metadata?: Promise<unknown>;
-  /** The TDF manifest. */
   manifest?: Promise<Manifest>;
-  /** If the source is a NanoTDF, this will be set. */
+  // If the source is a NanoTDF, this will be set.
   header?: Header;
 };
 
-/** Configuration options for the collection header cache. */
+// Configuration options for the collection header cache.
 export type RewrapCacheOptions = {
-  /** If we should disable (bypass) the cache. */
+  // If we should disable (bypass) the cache.
   bypass?: boolean;
 
-  /** Evict keys after this many milliseconds. */
+  // Evict keys after this many milliseconds.
   maxAge?: number;
 
-  /** Check for expired keys once every this many milliseconds. */
+  // Check for expired keys once every this many milliseconds.
   pollInterval?: number;
 };
 
@@ -228,11 +215,10 @@ const defaultRewrapCacheOptions: Required<RewrapCacheOptions> = {
   pollInterval: 500,
 };
 
-/**
- * Cache for headers of nanotdf collections, to quickly open multiple entries of the same collection.
- * It has a demon that removes all keys that have not been accessed in the last 5 minutes.
- * To cancel the demon, and clear the cache, call `close()`.
- * */
+// Cache for headers of nanotdf collections.
+// This allows the SDK to quickly open multiple entries of the same collection.
+// It has a demon that removes all keys that have not been accessed in the last 5 minutes.
+// To cancel the demon, and clear the cache, call `close()`.
 export class RewrapCache {
   private cache?: Map<Uint8Array, { lastAccessTime: number; value: CryptoKey }>;
   private closer?: ReturnType<typeof setInterval>;
@@ -268,7 +254,6 @@ export class RewrapCache {
     return undefined;
   }
 
-  /** Set a key in the cache. */
   set(key: Uint8Array, value: CryptoKey) {
     if (!this.cache) {
       return;
@@ -276,7 +261,6 @@ export class RewrapCache {
     this.cache.set(key, { lastAccessTime: Date.now(), value });
   }
 
-  /** Close the cache and release any resources. */
   close() {
     if (this.closer !== undefined) {
       clearInterval(this.closer);
@@ -310,56 +294,19 @@ export type TDFReader = {
   attributes: () => Promise<string[]>;
 };
 
-/**
- * The main OpenTDF class that provides methods for creating and reading TDF files.
- * It supports both NanoTDF and ZTDF formats.
- * 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.
- * @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);
- *
- * const client = new OpenTDF({
- *   authProvider,
- *   platformUrl: 'https://platform.example.com',
- * });
- *
- * const cipherText = await client.createZTDF({
- *   source: { type: 'stream', location: source },
- *   autoconfigure: false,
- * });
- *
- * const clearText = await client.read({ type: 'stream', location: cipherText });
- * ```
- */
+// SDK for dealing with OpenTDF data and policy services.
 export class OpenTDF {
-  /** The platform URL */
+  // Configuration service and more is at this URL/connectRPC endpoint
   readonly platformUrl: string;
-  /** The policy service endpoint */
   readonly policyEndpoint: string;
-  /** The auth provider for the OpenTDF instance. */
   readonly authProvider: AuthProvider;
-  /** If DPoP is enabled for this instance. */
   readonly dpopEnabled: boolean;
-  /** Default options for creating TDF objects. */
   defaultCreateOptions: Omit<CreateOptions, 'source'>;
-  /** Default options for reading TDF objects. */
   defaultReadOptions: Omit<ReadOptions, 'source'>;
-  /** The DPoP keys for this instance, if any. */
   readonly dpopKeys: Promise<CryptoKeyPair>;
-  /** Cache for rewrapped keys */
+
+  // Header cache for reading nanotdf collections
   private readonly rewrapCache: RewrapCache;
-  /** The TDF3 client for encrypting and decrypting ZTDF files. */
   readonly tdf3Client: TDF3Client;
 
   constructor({
@@ -405,7 +352,6 @@ export class OpenTDF {
       );
   }
 
-  /** Creates a new NanoTDF stream. */
   async createNanoTDF(opts: CreateNanoTDFOptions): Promise<DecoratedStream> {
     opts = {
       ...this.defaultCreateOptions,
@@ -424,6 +370,7 @@ export class OpenTDF {
 
   /**
    * Creates a new collection object, which can be used to encrypt a series of data with the same policy.
+   * @returns
    */
   async createNanoTDFCollection(
     opts: CreateNanoTDFCollectionOptions
@@ -432,7 +379,6 @@ export class OpenTDF {
     return new Collection(this.authProvider, opts);
   }
 
-  /** Creates a new ZTDF stream. */
   async createZTDF(opts: CreateZTDFOptions): Promise<DecoratedStream> {
     opts = { ...this.defaultCreateOptions, ...opts };
     const oldStream = await this.tdf3Client.encrypt({
@@ -457,25 +403,26 @@ export class OpenTDF {
     return stream;
   }
 
-  /** Opens a TDF file for inspection and decryption. */
+  /**
+   * Opens a TDF file for inspection and decryption.
+   * @param opts the file to open, and any appropriate configuration options
+   * @returns
+   */
   open(opts: ReadOptions): TDFReader {
     opts = { ...this.defaultReadOptions, ...opts };
     return new UnknownTypeReader(this, opts, this.rewrapCache);
   }
 
-  /** Decrypts a TDF file. */
   async read(opts: ReadOptions): Promise<DecoratedStream> {
     const reader = this.open(opts);
     return reader.decrypt();
   }
 
-  /** Closes the OpenTDF instance and releases any resources. */
   close() {
     this.rewrapCache.close();
   }
 }
 
-/** A TDF reader that can automatically detect the TDF type. */
 class UnknownTypeReader {
   delegate: Promise<TDFReader>;
   state: 'init' | 'resolving' | 'loaded' | 'decrypting' | 'closing' | 'done' | 'error' = 'init';
@@ -487,7 +434,6 @@ class UnknownTypeReader {
     this.delegate = this.resolveType();
   }
 
-  /** Resolves the TDF type based on the file prefix. */
   async resolveType(): Promise<TDFReader> {
     if (this.state === 'done') {
       throw new ConfigurationError('reader is closed');
@@ -509,25 +455,21 @@ class UnknownTypeReader {
     throw new InvalidFileError(`unsupported format; prefix not recognized ${prefix}`);
   }
 
-  /** Decrypts the TDF file */
   async decrypt(): Promise<DecoratedStream> {
     const actual = await this.delegate;
     return actual.decrypt();
   }
 
-  /** Returns the attributes of the TDF file */
   async attributes(): Promise<string[]> {
     const actual = await this.delegate;
     return actual.attributes();
   }
 
-  /** Returns the manifest of the TDF file */
   async manifest(): Promise<Manifest> {
     const actual = await this.delegate;
     return actual.manifest();
   }
 
-  /** Closes the TDF reader */
   async close() {
     if (this.state === 'done') {
       return;
@@ -545,7 +487,6 @@ class UnknownTypeReader {
   }
 }
 
-/** A TDF reader for NanoTDF files. */
 class NanoTDFReader {
   container: Promise<NanoTDF>;
   constructor(
@@ -573,7 +514,6 @@ class NanoTDFReader {
     });
   }
 
-  /** Decrypts the NanoTDF file and returns a decorated stream. */
   async decrypt(): Promise<DecoratedStream> {
     const nanotdf = await this.container;
     const cachedDEK = this.rewrapCache.get(nanotdf.header.ephemeralPublicKey);
@@ -616,12 +556,10 @@ class NanoTDFReader {
 
   async close() {}
 
-  /** Returns blank manifest. NanoTDF has no manifest. */
   async manifest(): Promise<Manifest> {
     return {} as Manifest;
   }
 
-  /** Returns the attributes of the NanoTDF file. */
   async attributes(): Promise<string[]> {
     const nanotdf = await this.container;
     if (!nanotdf.header.policy?.content) {
@@ -636,7 +574,6 @@ class NanoTDFReader {
   }
 }
 
-/** A reader for TDF files. */
 class ZTDFReader {
   overview: Promise<InspectedTDFOverview>;
   constructor(
@@ -647,10 +584,6 @@ class ZTDFReader {
     this.overview = loadTDFStream(source);
   }
 
-  /**
-   * Decrypts the TDF file and returns a decorated stream.
-   * The stream will have a manifest and metadata attached if available.
-   */
   async decrypt(): Promise<DecoratedStream> {
     const {
       assertionVerificationKeys,
@@ -708,13 +641,11 @@ class ZTDFReader {
     // TODO figure out how to close a chunker, if we want to.
   }
 
-  /** Returns the manifest of the TDF file. */
   async manifest(): Promise<Manifest> {
     const overview = await this.overview;
     return overview.manifest;
   }
 
-  /** Returns the attributes of the TDF file. */
   async attributes(): Promise<string[]> {
     const manifest = await this.manifest();
     const policyJSON = base64.decode(manifest.encryptionInformation.policy);
@@ -735,18 +666,13 @@ async function streamify(ab: Promise<ArrayBuffer>): Promise<ReadableStream<Uint8
   return stream;
 }
 
-/** A writer for NanoTDF collections. */
 export type NanoTDFCollectionWriter = {
-  /** The NanoTDF client used for encrypting data in this collection. */
   encrypt: (source: Source) => Promise<ReadableStream<Uint8Array>>;
-  /** Closes the collection and releases any resources. */
   close: () => Promise<void>;
 };
 
 class Collection {
-  /** The NanoTDF client used for encrypting data in this collection. */
   client?: NanoTDFDatasetClient;
-  /** Options for encrypting data in this collection. */
   encryptOptions?: NanoEncryptOptions;
 
   constructor(authProvider: AuthProvider, opts: CreateNanoTDFCollectionOptions) {
@@ -779,7 +705,6 @@ class Collection {
     });
   }
 
-  /** Encrypts a source into a NanoTDF stream. */
   async encrypt(source: Source): Promise<DecoratedStream> {
     if (!this.client) {
       throw new ConfigurationError('Collection is closed');
@@ -797,7 +722,6 @@ class Collection {
     return stream;
   }
 
-  /** Releases client resources. */
   async close() {
     delete this.client;
   }

package/src/platform.ts

@@ -33,11 +33,11 @@ export interface PlatformServices {
 }
 
 export interface PlatformClientOptions {
-  /** Optional authentication provider for generating auth interceptor. */
+  // Optional authentication provider for generating auth interceptor.
   authProvider?: AuthProvider;
-  /** Array of custom interceptors to apply to rpc requests. */
+  // Array of custom interceptors to apply to rpc requests.
   interceptors?: Interceptor[];
-  /** Base URL of the platform API. */
+  // Base URL of the platform API.
   platformUrl: string;
 }
 
@@ -50,22 +50,8 @@ export interface PlatformClientOptions {
  *
  * This client supports authentication via an `AuthProvider` or custom interceptors, which can
  * be used to add authentication headers or other custom logic to outgoing requests.
- * @example
- * ```
- * import { AuthProviders, OpenTDF } from '@opentdf/sdk';
- * import { PlatformClient } from '@opentdf/sdk/platform';
  *
- * const authProvider: AuthProvider = await AuthProviders.refreshAuthProvider({...});
- * const platform = new PlatformClient({
- *   authProvider,
- *   platformUrl: 'https://platform.example.com',
- * });
- *
- * const wellKnownResponse = await platform.v1.wellknown.getWellKnownConfiguration({});
- * console.log('Well-known configuration:', wellKnownResponse.configuration);
- * ```
  */
-
 export class PlatformClient {
   readonly v1: PlatformServices;
 
@@ -110,6 +96,8 @@ export class PlatformClient {
  * that returns an object containing authentication headers. These headers are then
  * added to the request before it is sent to the server.
  *
+ * @param authProvider - An instance of `AuthProvider` used to generate authentication credentials.
+ * @returns An `Interceptor` function that modifies requests to include authentication headers.
  */
 function createAuthInterceptor(authProvider: AuthProvider): Interceptor {
   const authInterceptor: Interceptor = (next) => async (req) => {

package/src/seekable.ts

@@ -33,30 +33,12 @@ export const fromBrowserFile = (fileRef: Blob): Chunker => {
   };
 };
 
-/**
- * Creates a seekable object from a buffer.
- * @param source A Uint8Array to read from.
- * If byteStart and byteEnd are not provided, reads the entire array.
- * If byteStart is provided, reads from that index to the end of the array.
- * If byteEnd is provided, reads from byteStart to byteEnd (exclusive).
- * If both byteStart and byteEnd are provided, reads from byteStart to byteEnd (exclusive).
- * @returns A promise that resolves to a Uint8Array containing the requested data.
- */
 export const fromBuffer = (source: Uint8Array): Chunker => {
   return (byteStart?: number, byteEnd?: number) => {
     return Promise.resolve(source.slice(byteStart, byteEnd));
   };
 };
 
-/**
- * Creates a seekable object from a string.
- * @param source A string to read from.
- * If byteStart and byteEnd are not provided, reads the entire string.
- * If byteStart is provided, reads from that index to the end of the string.
- * If byteEnd is provided, reads from byteStart to byteEnd (exclusive).
- * If both byteStart and byteEnd are provided, reads from byteStart to byteEnd (exclusive).
- * @returns A promise that resolves to a Uint8Array containing the requested data.
- */
 export const fromString = (source: string): Chunker => {
   return fromBuffer(new TextEncoder().encode(source));
 };
@@ -128,12 +110,6 @@ export const fromUrl = async (location: string): Promise<Chunker> => {
   };
 };
 
-/**
- * Creates a seekable object from a source.
- * @param source A Source object containing the type and location of the data.
- * @returns A promise that resolves to a Chunker function.
- * @throws ConfigurationError if the source type is not supported or the location is invalid.
- */
 export const fromSource = async ({ type, location }: Source): Promise<Chunker> => {
   switch (type) {
     case 'buffer':
@@ -163,13 +139,6 @@ export const fromSource = async ({ type, location }: Source): Promise<Chunker> =
   }
 };
 
-/**
- * Converts a Source object to a ReadableStream.
- * @param source A Source object containing the type and location of the data.
- * Converts the source to a ReadableStream of Uint8Array.
- * This is useful for streaming data from various sources like files, remote URLs, or chunkers.
- * @returns A ReadableStream of Uint8Array.
- */
 export async function sourceToStream(source: Source): Promise<ReadableStream<Uint8Array>> {
   switch (source.type) {
     case 'stream':