@opentdf/sdk 0.14.0-rc.133 → 0.16.0

package/src/opentdf.ts

@@ -153,6 +153,18 @@ export type ReadOptions = {
   /** If set, prevents more than this number of concurrent requests to the KAS. */
   concurrencyLimit?: number;
 
+  /**
+   * Maximum number of payload segments to fetch and decrypt per batch.
+   * Adjust together with `maxConcurrentSegmentBatches` for expected throughput.
+   */
+  segmentBatchSize?: number;
+
+  /**
+   * Maximum number of segment batches that may be fetched concurrently.
+   * Adjust together with `segmentBatchSize` for expected throughput.
+   */
+  maxConcurrentSegmentBatches?: number;
+
   /** Type of key to use for wrapping responses. */
   wrappingKeyAlgorithm?: KasPublicKeyAlgorithm;
 };
@@ -495,7 +507,9 @@ class ZTDFReader {
   async decrypt(): Promise<DecoratedStream> {
     const {
       assertionVerificationKeys,
+      maxConcurrentSegmentBatches,
       noVerify: noVerifyAssertions,
+      segmentBatchSize,
       wrappingKeyAlgorithm,
     } = this.opts;
 
@@ -534,7 +548,9 @@ class ZTDFReader {
         keyMiddleware: async (k) => k,
         progressHandler: this.client.clientConfig.progressHandler,
         assertionVerificationKeys,
+        maxConcurrentSegmentBatches,
         noVerifyAssertions,
+        segmentBatchSize,
         wrappingKeyAlgorithm,
         fulfillableObligations: this.opts.fulfillableObligationFQNs || [],
       },

package/src/platform/authorization/entity-identifiers.ts

@@ -35,7 +35,8 @@ import {
  * });
  *
  * // After
- * const eid = forEmail('jen@example.com');
+ * import { EntityIdentifiers } from '@opentdf/sdk';
+ * const eid = EntityIdentifiers.forEmail('jen@example.com');
  * ```
  */
 

package/src/platform/authorization/resources.ts

@@ -0,0 +1,59 @@
+import { create } from '@bufbuild/protobuf';
+import {
+  type Resource,
+  ResourceSchema,
+  Resource_AttributeValuesSchema,
+} from './v2/authorization_pb.js';
+
+/**
+ * Convenience constructors for {@link Resource}, analogous to the
+ * {@link EntityIdentifiers} helpers for {@link EntityIdentifier}.
+ *
+ * Each function builds a complete `Resource` so callers avoid deeply nested
+ * object literals.
+ *
+ * @example
+ * ```ts
+ * // Before
+ * const resource = create(ResourceSchema, {
+ *   resource: {
+ *     case: 'attributeValues',
+ *     value: create(Resource_AttributeValuesSchema, {
+ *       fqns: ['https://example.com/attr/department/value/finance'],
+ *     }),
+ *   },
+ * });
+ *
+ * // After
+ * import { Resources } from '@opentdf/sdk';
+ * const resource = Resources.forAttributeValues('https://example.com/attr/department/value/finance');
+ * ```
+ */
+
+/**
+ * Returns a Resource containing the given attribute value FQNs.
+ * This is the most common Resource variant, used when authorizing against
+ * attribute values attached to data (e.g. those on a TDF).
+ */
+export function forAttributeValues(fqn: string, ...moreFqns: string[]): Resource {
+  const fqns = [fqn, ...moreFqns];
+  return create(ResourceSchema, {
+    resource: {
+      case: 'attributeValues',
+      value: create(Resource_AttributeValuesSchema, { fqns }),
+    },
+  });
+}
+
+/**
+ * Returns a Resource that references a single registered resource value
+ * by its fully qualified name, as stored in platform policy.
+ */
+export function forRegisteredResourceValueFqn(fqn: string): Resource {
+  return create(ResourceSchema, {
+    resource: {
+      case: 'registeredResourceValueFqn',
+      value: fqn,
+    },
+  });
+}

package/src/version.ts

@@ -1,7 +1,7 @@
 /**
  * Exposes the released version number of the `@opentdf/sdk` package
  */
-export const version = '0.14.0'; // x-release-please-version
+export const version = '0.16.0'; // x-release-please-version
 
 /**
  * A string name used to label requests as coming from this library client.

package/tdf3/src/ciphers/aes-gcm-cipher.ts

@@ -1,6 +1,7 @@
 import { Binary } from '../binary.js';
 import { Algorithms } from './algorithms.js';
 import { SymmetricCipher } from './symmetric-cipher-base.js';
+import { decryptBufferSource } from '../crypto/core/symmetric.js';
 import { concatUint8 } from '../utils/index.js';
 
 import {
@@ -16,20 +17,17 @@ const IV_LENGTH = 12;
 type ProcessGcmPayload = {
   payload: Binary;
   payloadIv: Binary;
-  payloadAuthTag: Binary;
 };
 // Should this be a Binary, Buffer, or... both?
 function processGcmPayload(source: ArrayBuffer): ProcessGcmPayload {
   // Read the 12 byte IV from the beginning of the stream
   const payloadIv = Binary.fromArrayBuffer(source.slice(0, 12));
 
-  // Slice the final 16 bytes of the buffer for the authentication tag
-  const payloadAuthTag = Binary.fromArrayBuffer(source.slice(-16));
-
   return {
-    payload: Binary.fromArrayBuffer(source.slice(12, -16)),
+    // WebCrypto AES-GCM expects ciphertext with the auth tag appended, so keep
+    // the tag attached instead of splitting and re-concatenating it later.
+    payload: Binary.fromArrayBuffer(source.slice(12)),
     payloadIv,
-    payloadAuthTag,
   };
 }
 
@@ -64,18 +62,25 @@ export class AesGcmCipher extends SymmetricCipher {
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   override async decrypt(
-    buffer: ArrayBuffer,
+    buffer: ArrayBuffer | Uint8Array,
     key: SymmetricKey,
     iv?: Binary
   ): Promise<DecryptResult> {
-    const { payload, payloadIv, payloadAuthTag } = processGcmPayload(buffer);
+    const input = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+
+    if (this.cryptoService.name === 'BrowserNativeCryptoService') {
+      return decryptBufferSource(
+        input.subarray(12),
+        key,
+        input.subarray(0, 12),
+        Algorithms.AES_256_GCM
+      );
+    }
 
-    return this.cryptoService.decrypt(
-      payload,
-      key,
-      payloadIv,
-      Algorithms.AES_256_GCM,
-      payloadAuthTag
+    const { payload, payloadIv } = processGcmPayload(
+      input.buffer.slice(input.byteOffset, input.byteOffset + input.byteLength)
     );
+
+    return this.cryptoService.decrypt(payload, key, payloadIv, Algorithms.AES_256_GCM);
   }
 }

package/tdf3/src/ciphers/symmetric-cipher-base.ts

@@ -37,5 +37,9 @@ export abstract class SymmetricCipher {
 
   abstract encrypt(payload: Binary, key: SymmetricKey, iv: Binary): Promise<EncryptResult>;
 
-  abstract decrypt(payload: Uint8Array, key: SymmetricKey, iv?: Binary): Promise<DecryptResult>;
+  abstract decrypt(
+    payload: ArrayBuffer | Uint8Array,
+    key: SymmetricKey,
+    iv?: Binary
+  ): Promise<DecryptResult>;
 }

package/tdf3/src/client/builders.ts

@@ -536,6 +536,8 @@ export type DecryptParams = {
   streamMiddleware?: DecryptStreamMiddleware;
   assertionVerificationKeys?: AssertionVerificationKeys;
   concurrencyLimit?: number;
+  segmentBatchSize?: number;
+  maxConcurrentSegmentBatches?: number;
   noVerifyAssertions?: boolean;
   wrappingKeyAlgorithm?: KasPublicKeyAlgorithm;
   fulfillableObligationFQNs?: string[];
@@ -725,6 +727,24 @@ class DecryptParamsBuilder {
     return this;
   }
 
+  /**
+   * Set the number of payload segments to fetch and decrypt per batch.
+   * Adjust together with `withMaxConcurrentSegmentBatches()` for expected throughput.
+   */
+  withSegmentBatchSize(size: number): DecryptParamsBuilder {
+    this._params.segmentBatchSize = size;
+    return this;
+  }
+
+  /**
+   * Set the maximum number of payload segment batches to fetch concurrently.
+   * Adjust together with `withSegmentBatchSize()` for expected throughput.
+   */
+  withMaxConcurrentSegmentBatches(limit: number): DecryptParamsBuilder {
+    this._params.maxConcurrentSegmentBatches = limit;
+    return this;
+  }
+
   /**
    * Generate a parameters object in the form expected by <code>{@link Client#decrypt|decrypt}</code>.
    * <br/><br/>

package/tdf3/src/client/index.ts

@@ -800,6 +800,8 @@ export class Client {
     assertionVerificationKeys,
     noVerifyAssertions,
     concurrencyLimit = 1,
+    maxConcurrentSegmentBatches,
+    segmentBatchSize,
     wrappingKeyAlgorithm,
     fulfillableObligationFQNs = [],
   }: DecryptParams): Promise<DecoratedReadableStream> {
@@ -836,7 +838,9 @@ export class Client {
         keyMiddleware,
         progressHandler: this.clientConfig.progressHandler,
         assertionVerificationKeys,
+        maxConcurrentSegmentBatches,
         noVerifyAssertions,
+        segmentBatchSize,
         wrappingKeyAlgorithm,
         fulfillableObligations: fulfillableObligationFQNs,
       })

package/tdf3/src/crypto/core/symmetric.ts

@@ -13,6 +13,16 @@ import { unwrapSymmetricKey, wrapSymmetricKey } from './keys.js';
 
 const ENC_DEC_METHODS: KeyUsage[] = ['encrypt', 'decrypt'];
 
+function asUint8ArrayView(buffer: BufferSource): Uint8Array {
+  if (buffer instanceof Uint8Array) {
+    return buffer;
+  }
+  if (ArrayBuffer.isView(buffer)) {
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  }
+  return new Uint8Array(buffer);
+}
+
 /**
  * Generate a random symmetric key (opaque).
  * @param length - Key length in bytes (default 32 for AES-256)
@@ -61,7 +71,23 @@ export function decrypt(
   algorithm?: AlgorithmUrn,
   authTag?: Binary
 ): Promise<DecryptResult> {
-  return _doDecrypt(payload, key, iv, algorithm, authTag);
+  return _doDecryptBufferSource(
+    payload.asArrayBuffer(),
+    key,
+    iv.asArrayBuffer(),
+    algorithm,
+    authTag?.asArrayBuffer()
+  );
+}
+
+export function decryptBufferSource(
+  payload: BufferSource,
+  key: SymmetricKey,
+  iv: BufferSource,
+  algorithm?: AlgorithmUrn,
+  authTag?: BufferSource
+): Promise<DecryptResult> {
+  return _doDecryptBufferSource(payload, key, iv, algorithm, authTag);
 }
 
 /**
@@ -115,32 +141,33 @@ async function _doEncrypt(
   };
 }
 
-async function _doDecrypt(
-  payload: Binary,
+async function _doDecryptBufferSource(
+  payload: BufferSource,
   key: SymmetricKey,
-  iv: Binary,
+  iv: BufferSource,
   algorithm?: AlgorithmUrn,
-  authTag?: Binary
+  authTag?: BufferSource
 ): Promise<DecryptResult> {
   console.assert(payload != null);
   console.assert(key != null);
   console.assert(iv != null);
 
-  let payloadBuffer = payload.asArrayBuffer();
+  let payloadBuffer: BufferSource = payload;
 
   // Concat the the auth tag to the payload for decryption
   if (authTag) {
-    const authTagBuffer = authTag.asArrayBuffer();
-    const gcmPayload = new Uint8Array(payloadBuffer.byteLength + authTagBuffer.byteLength);
-    gcmPayload.set(new Uint8Array(payloadBuffer), 0);
-    gcmPayload.set(new Uint8Array(authTagBuffer), payloadBuffer.byteLength);
-    payloadBuffer = gcmPayload.buffer;
+    const payloadBytes = asUint8ArrayView(payloadBuffer);
+    const authTagBytes = asUint8ArrayView(authTag);
+    const gcmPayload = new Uint8Array(payloadBytes.byteLength + authTagBytes.byteLength);
+    gcmPayload.set(payloadBytes, 0);
+    gcmPayload.set(authTagBytes, payloadBytes.byteLength);
+    payloadBuffer = gcmPayload;
   }
 
-  const algoDomString = getSymmetricAlgoDomString(iv, algorithm);
+  const ivBytes = asUint8ArrayView(iv);
+  const algoDomString = getSymmetricAlgoDomStringFromIv(ivBytes, algorithm);
   const keyBytes = unwrapSymmetricKey(key);
   const importedKey = await _importKey(keyBytes, algoDomString);
-  algoDomString.iv = iv.asArrayBuffer();
 
   const decrypted = await crypto.subtle
     .decrypt(algoDomString, importedKey, payloadBuffer)
@@ -168,6 +195,13 @@ function _importKey(keyBytes: Uint8Array, algorithm: AesCbcParams | AesGcmParams
 function getSymmetricAlgoDomString(
   iv: Binary,
   algorithm?: AlgorithmUrn
+): AesCbcParams | AesGcmParams {
+  return getSymmetricAlgoDomStringFromIv(asUint8ArrayView(iv.asArrayBuffer()), algorithm);
+}
+
+function getSymmetricAlgoDomStringFromIv(
+  iv: Uint8Array,
+  algorithm?: AlgorithmUrn
 ): AesCbcParams | AesGcmParams {
   let nativeAlgorithm = 'AES-CBC';
   if (algorithm === Algorithms.AES_256_GCM) {
@@ -176,7 +210,7 @@ function getSymmetricAlgoDomString(
 
   return {
     name: nativeAlgorithm,
-    iv: iv.asArrayBuffer(),
+    iv,
   };
 }
 

package/tdf3/src/models/encryption-information.ts

@@ -72,7 +72,7 @@ export class SplitKey {
     return this.cipher.encrypt(contentBinary, key, ivBinary);
   }
 
-  async decrypt(content: Uint8Array, key: SymmetricKey): Promise<DecryptResult> {
+  async decrypt(content: ArrayBuffer | Uint8Array, key: SymmetricKey): Promise<DecryptResult> {
     return this.cipher.decrypt(content, key);
   }