@opentdf/sdk 0.4.0-beta.40 → 0.4.0-beta.41

package/src/nanotdf/Client.ts

@@ -10,10 +10,16 @@ import {
 } from '../access.js';
 import { AuthProvider, isAuthProvider, reqSignature } from '../auth/providers.js';
 import { ConfigurationError, DecryptError, TdfError, UnsafeUrlError } from '../errors.js';
-import { cryptoPublicToPem, pemToCryptoPublicKey, validateSecureUrl } from '../utils.js';
+import {
+  cryptoPublicToPem,
+  getRequiredObligationFQNs,
+  pemToCryptoPublicKey,
+  validateSecureUrl,
+} from '../utils.js';
 
 export interface ClientConfig {
   allowedKases?: string[];
+  fulfillableObligationFQNs?: string[];
   ignoreAllowList?: boolean;
   authProvider: AuthProvider;
   dpopEnabled?: boolean;
@@ -23,6 +29,11 @@ export interface ClientConfig {
   platformUrl: string;
 }
 
+type RewrapKeyResult = {
+  unwrappedKey: CryptoKey;
+  requiredObligations: string[];
+};
+
 function toJWSAlg(c: CryptoKey): string {
   const { algorithm } = c;
   switch (algorithm.name) {
@@ -106,6 +117,7 @@ export default class Client {
   static readonly IV_SIZE = 12;
 
   allowedKases?: OriginAllowList;
+  readonly fulfillableObligationFQNs: string[];
   /*
     These variables are expected to be either assigned during initialization or within the methods.
     This is needed as the flow is very specific. Errors should be thrown if the necessary step is not completed.
@@ -168,6 +180,7 @@ export default class Client {
     } else {
       const {
         allowedKases,
+        fulfillableObligationFQNs = [],
         ignoreAllowList,
         authProvider,
         dpopEnabled,
@@ -184,6 +197,7 @@ export default class Client {
       if (allowedKases?.length || ignoreAllowList) {
         this.allowedKases = new OriginAllowList(allowedKases || [], ignoreAllowList);
       }
+      this.fulfillableObligationFQNs = fulfillableObligationFQNs;
       this.dpopEnabled = !!dpopEnabled;
       if (dpopKeys) {
         this.requestSignerKeyPair = dpopKeys;
@@ -223,7 +237,7 @@ export default class Client {
     kasRewrapUrl: string,
     magicNumberVersion: ArrayBufferLike,
     clientVersion: string
-  ): Promise<CryptoKey> {
+  ): Promise<RewrapKeyResult> {
     let allowedKases = this.allowedKases;
 
     if (!allowedKases) {
@@ -265,10 +279,15 @@ export default class Client {
     });
 
     // Wrapped
-    const wrappedKey = await fetchWrappedKey(kasRewrapUrl, signedRequestToken, this.authProvider);
+    const rewrapResp = await fetchWrappedKey(
+      kasRewrapUrl,
+      signedRequestToken,
+      this.authProvider,
+      this.fulfillableObligationFQNs
+    );
 
     // Extract the iv and ciphertext
-    const entityWrappedKey = wrappedKey.entityWrappedKey;
+    const entityWrappedKey = rewrapResp.entityWrappedKey;
     const ivLength =
       clientVersion == Client.SDK_INITIAL_RELEASE ? Client.INITIAL_RELEASE_IV_SIZE : Client.IV_SIZE;
     const iv = entityWrappedKey.subarray(0, ivLength);
@@ -277,7 +296,7 @@ export default class Client {
     let kasPublicKey;
     try {
       // Let us import public key as a cert or public key
-      kasPublicKey = await pemToCryptoPublicKey(wrappedKey.sessionPublicKey);
+      kasPublicKey = await pemToCryptoPublicKey(rewrapResp.sessionPublicKey);
     } catch (cause) {
       throw new ConfigurationError(
         `internal: [${kasRewrapUrl}] PEM Public Key to crypto public key failed. Is PEM formatted correctly?`,
@@ -346,6 +365,9 @@ export default class Client {
       throw new DecryptError('Unable to import raw key.', cause);
     }
 
-    return unwrappedKey;
+    return {
+      requiredObligations: getRequiredObligationFQNs(rewrapResp),
+      unwrappedKey: unwrappedKey,
+    };
   }
 }

package/src/opentdf.ts

@@ -55,6 +55,12 @@ export type Keys = {
   [keyID: string]: CryptoKey | CryptoKeyPair;
 };
 
+/** The fully qualified obligations that the caller is required to fulfill. */
+export type RequiredObligations = {
+  /** List of obligations values' fully qualified names. */
+  fqns: string[];
+};
+
 /** Options for creating a new TDF object, shared between all container types. */
 export type CreateOptions = {
   /** If the policy service should be used to control creation options. */
@@ -156,6 +162,8 @@ export type ReadOptions = {
   allowedKASEndpoints?: string[];
   /** Optionally disable checking the allowlist. */
   ignoreAllowlist?: boolean;
+  /** Optionally override client fulfillableObligationFQNs. */
+  fulfillableObligationFQNs?: string[];
   /** Public (or shared) keys for verifying assertions. */
   assertionVerificationKeys?: AssertionVerificationKeys;
   /** Optionally disable assertion verification. */
@@ -307,6 +315,11 @@ export type TDFReader = {
    * @returns Any data attributes found in the policy. Currently only works for plain text, embedded policies (not remote or encrypted policies)
    */
   attributes: () => Promise<string[]>;
+
+  /**
+   * @returns Any obligation value FQNs that are required to be fulfilled on the TDF, populated during the decrypt flow.
+   */
+  obligations: () => Promise<RequiredObligations>;
 };
 
 /**
@@ -543,11 +556,18 @@ class UnknownTypeReader {
       this.state = 'done';
     });
   }
+
+  async obligations() {
+    const actual = await this.delegate;
+    return actual.obligations();
+  }
 }
 
 /** A TDF reader for NanoTDF files. */
 class NanoTDFReader {
   container: Promise<NanoTDF>;
+  // Required obligation FQNs that must be fulfilled, provided via the decrypt flow.
+  private requiredObligations?: RequiredObligations;
   constructor(
     readonly outer: OpenTDF,
     readonly opts: ReadOptions,
@@ -573,7 +593,10 @@ class NanoTDFReader {
     });
   }
 
-  /** Decrypts the NanoTDF file and returns a decorated stream. */
+  /**
+   * Decrypts the NanoTDF file and returns a decorated stream.
+   * Sets required obligations on the reader when retrieved from KAS rewrap response.
+   */
   async decrypt(): Promise<DecoratedStream> {
     const nanotdf = await this.container;
     const cachedDEK = this.rewrapCache.get(nanotdf.header.ephemeralPublicKey);
@@ -587,6 +610,7 @@ class NanoTDFReader {
       this.opts.allowedKASEndpoints?.[0] || platformUrl || 'https://disallow.all.invalid';
     const nc = new Client({
       allowedKases: this.opts.allowedKASEndpoints,
+      fulfillableObligationFQNs: this.opts.fulfillableObligationFQNs,
       authProvider: this.outer.authProvider,
       ignoreAllowList: this.opts.ignoreAllowlist,
       dpopEnabled: this.outer.dpopEnabled,
@@ -597,7 +621,7 @@ class NanoTDFReader {
     // TODO: The version number should be fetched from the API
     const version = '0.0.1';
     // Rewrap key on every request
-    const dek = await nc.rewrapKey(
+    const { unwrappedKey: dek, requiredObligations } = await nc.rewrapKey(
       nanotdf.header.toBuffer(),
       nanotdf.header.getKasRewrapUrl(),
       nanotdf.header.magicNumberVersion,
@@ -607,6 +631,7 @@ class NanoTDFReader {
       // These should have thrown already.
       throw new Error('internal: key rewrap failure');
     }
+    this.requiredObligations = { fqns: requiredObligations };
     this.rewrapCache.set(nanotdf.header.ephemeralPublicKey, dek);
     const r: DecoratedStream = await streamify(decryptNanoTDF(dek, nanotdf));
     // TODO figure out how to attach policy and metadata to the stream
@@ -634,11 +659,25 @@ class NanoTDFReader {
     const policy = JSON.parse(policyString) as Policy;
     return policy?.body?.dataAttributes.map((a) => a.attribute) || [];
   }
+
+  /**
+   * Returns obligations populated from the decrypt flow.
+   * If a decrypt has not occurred, attempts one to retrieve obligations.
+   */
+  async obligations(): Promise<RequiredObligations> {
+    if (this.requiredObligations) {
+      return this.requiredObligations;
+    }
+    await this.decrypt();
+    return this.requiredObligations ?? { fqns: [] };
+  }
 }
 
 /** A reader for TDF files. */
 class ZTDFReader {
   overview: Promise<InspectedTDFOverview>;
+  // Required obligation FQNs that must be fulfilled, provided via the decrypt flow.
+  private requiredObligations?: RequiredObligations;
   constructor(
     readonly client: TDF3Client,
     readonly opts: ReadOptions,
@@ -650,6 +689,7 @@ class ZTDFReader {
   /**
    * Decrypts the TDF file and returns a decorated stream.
    * The stream will have a manifest and metadata attached if available.
+   * Sets required obligations on the reader when retrieved from KAS rewrap response.
    */
   async decrypt(): Promise<DecoratedStream> {
     const {
@@ -695,9 +735,13 @@ class ZTDFReader {
         assertionVerificationKeys,
         noVerifyAssertions,
         wrappingKeyAlgorithm,
+        fulfillableObligations: this.opts.fulfillableObligationFQNs || [],
       },
       overview
     );
+    this.requiredObligations = {
+      fqns: oldStream.obligations(),
+    };
     const stream: DecoratedStream = oldStream.stream;
     stream.manifest = Promise.resolve(overview.manifest);
     stream.metadata = Promise.resolve(oldStream.metadata);
@@ -721,6 +765,18 @@ class ZTDFReader {
     const policy = JSON.parse(policyJSON) as Policy;
     return policy?.body?.dataAttributes.map((a) => a.attribute) || [];
   }
+
+  /**
+   * Returns obligations populated from the decrypt flow.
+   * If a decrypt has not occurred, attempts one to retrieve obligations.
+   */
+  async obligations(): Promise<RequiredObligations> {
+    if (this.requiredObligations) {
+      return this.requiredObligations;
+    }
+    await this.decrypt();
+    return this.requiredObligations ?? { fqns: [] };
+  }
 }
 
 async function streamify(ab: Promise<ArrayBuffer>): Promise<ReadableStream<Uint8Array>> {

package/src/platform.ts

@@ -8,6 +8,7 @@ import { AuthProvider } from '../tdf3/index.js';
 import { Client, createClient, Interceptor } from '@connectrpc/connect';
 import { WellKnownService } from './platform/wellknownconfiguration/wellknown_configuration_pb.js';
 import { AuthorizationService } from './platform/authorization/authorization_pb.js';
+import { AuthorizationService as AuthorizationServiceV2 } from './platform/authorization/v2/authorization_pb.js';
 import { EntityResolutionService } from './platform/entityresolution/entity_resolution_pb.js';
 import { AccessService } from './platform/kas/kas_pb.js';
 import { ActionService } from './platform/policy/actions/actions_pb.js';
@@ -32,6 +33,10 @@ export interface PlatformServices {
   wellknown: Client<typeof WellKnownService>;
 }
 
+export interface PlatformServicesV2 {
+  authorization: Client<typeof AuthorizationServiceV2>;
+}
+
 export interface PlatformClientOptions {
   /** Optional authentication provider for generating auth interceptor. */
   authProvider?: AuthProvider;
@@ -68,6 +73,7 @@ export interface PlatformClientOptions {
 
 export class PlatformClient {
   readonly v1: PlatformServices;
+  readonly v2: PlatformServicesV2;
 
   constructor(options: PlatformClientOptions) {
     const interceptors: Interceptor[] = [];
@@ -99,6 +105,10 @@ export class PlatformClient {
       unsafe: createClient(UnsafeService, transport),
       wellknown: createClient(WellKnownService, transport),
     };
+
+    this.v2 = {
+      authorization: createClient(AuthorizationServiceV2, transport),
+    };
   }
 }
 

package/src/utils.ts

@@ -3,8 +3,11 @@ import { exportSPKI, importX509 } from 'jose';
 import { base64 } from './encodings/index.js';
 import { pemCertToCrypto, pemPublicToCrypto } from './nanotdf-crypto/pemPublicToCrypto.js';
 import { ConfigurationError } from './errors.js';
+import { RewrapResponse } from './platform/kas/kas_pb.js';
 import { ConnectError } from '@connectrpc/connect';
 
+const REQUIRED_OBLIGATIONS_METADATA_KEY = 'X-Required-Obligations';
+
 /**
  * Check to see if the given URL is 'secure'. This assumes:
  *
@@ -223,3 +226,32 @@ export function getPlatformUrlFromKasEndpoint(endpoint: string): string {
   }
   return result;
 }
+
+/**
+ * Retrieves the fully qualified Obligations (values) that must be fulfilled from a rewrap response.
+ */
+export function getRequiredObligationFQNs(response: RewrapResponse) {
+  const requiredObligations = new Set<string>();
+
+  // Loop through response key access object results, checking proto values/types for a metadata key
+  // that matches the expected KAS-provided fulfillable obligations list.
+  for (const resp of response.responses) {
+    for (const result of resp.results) {
+      if (!result.metadata.hasOwnProperty(REQUIRED_OBLIGATIONS_METADATA_KEY)) {
+        continue;
+      }
+      const value = result.metadata[REQUIRED_OBLIGATIONS_METADATA_KEY];
+      if (value?.kind.case !== 'listValue') {
+        continue;
+      }
+      const obligations = value.kind.value.values;
+      for (const obligation of obligations) {
+        if (obligation.kind.case === 'stringValue') {
+          requiredObligations.add(obligation.kind.value.toLowerCase());
+        }
+      }
+    }
+  }
+
+  return [...requiredObligations.values()];
+}

package/tdf3/src/client/DecoratedReadableStream.ts

@@ -21,6 +21,7 @@ export class DecoratedReadableStream {
   metadata?: Metadata;
   manifest: Manifest;
   fileStreamServiceWorker?: string;
+  requiredObligations?: string[];
 
   constructor(
     underlyingSource: UnderlyingSource & {
@@ -60,6 +61,14 @@ export class DecoratedReadableStream {
   async toString(): Promise<string> {
     return new Response(this.stream).text();
   }
+
+  /**
+   * The fully qualified obligations required to be fulfilled on stream contents
+   * are set as decoration during the decrypt flow.
+   */
+  obligations(): string[] {
+    return this.requiredObligations ?? [];
+  }
 }
 
 export function isDecoratedReadableStream(s: unknown): s is DecoratedReadableStream {

package/tdf3/src/client/builders.ts

@@ -538,6 +538,7 @@ export type DecryptParams = {
   concurrencyLimit?: number;
   noVerifyAssertions?: boolean;
   wrappingKeyAlgorithm?: KasPublicKeyAlgorithm;
+  fulfillableObligationFQNs?: string[];
 };
 
 /**

package/tdf3/src/client/index.ts

@@ -143,6 +143,12 @@ export interface ClientConfig {
    * Defaults to `[]`.
    */
   allowedKases?: string[];
+  /**
+   * List of obligation value FQNs in platform policy that can be fulfilled
+   * by the PEP handling this client (i.e. 'https://example.com/obl/drm/value/mask').
+   * Defaults to '[]'.
+   */
+  fulfillableObligationFQNs?: string[];
   // Platform URL to use to lookup allowed KASes when allowedKases is empty
   platformUrl?: string;
   ignoreAllowList?: boolean;
@@ -337,6 +343,13 @@ export class Client {
    */
   readonly allowedKases?: OriginAllowList;
 
+  /**
+   * List of obligation value FQNs in platform policy that can be fulfilled
+   * by the PEP utilizing this client (i.e. 'https://example.com/obl/drm/value/mask').
+   * Defaults to '[]'. Currently set per Client and not per TDF.
+   */
+  readonly fulfillableObligationFQNs: string[];
+
   /**
    * URL of the platform, required to fetch list of allowed KASes when allowedKases is empty
    */
@@ -417,6 +430,14 @@ export class Client {
       }
     }
 
+    this.fulfillableObligationFQNs = config.fulfillableObligationFQNs?.length
+      ? config.fulfillableObligationFQNs
+      : [];
+
+    if (clientConfig.easEndpoint) {
+      this.easEndpoint = clientConfig.easEndpoint;
+    }
+
     this.authProvider = config.authProvider;
     this.clientConfig = clientConfig;
 
@@ -736,6 +757,7 @@ export class Client {
    * @param params.source A data stream object, one of remote, stream, buffer, etc. types.
    * @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.
    * @see DecryptParamsBuilder
    */
@@ -748,6 +770,7 @@ export class Client {
     noVerifyAssertions,
     concurrencyLimit = 1,
     wrappingKeyAlgorithm,
+    fulfillableObligationFQNs = [],
   }: DecryptParams): Promise<DecoratedReadableStream> {
     const dpopKeys = await this.dpopKeys;
     if (!this.authProvider) {
@@ -762,6 +785,12 @@ export class Client {
       throw new ConfigurationError('platformUrl is required when allowedKases is empty');
     }
 
+    const hasEmptyDecryptParamObligationsButGlobal =
+      !fulfillableObligationFQNs.length && this.fulfillableObligationFQNs.length;
+    if (hasEmptyDecryptParamObligationsButGlobal) {
+      fulfillableObligationFQNs = this.fulfillableObligationFQNs;
+    }
+
     // Await in order to catch any errors from this call.
     // TODO: Write error event to stream and don't await.
     return await (streamMiddleware as DecryptStreamMiddleware)(
@@ -778,6 +807,7 @@ export class Client {
         assertionVerificationKeys,
         noVerifyAssertions,
         wrappingKeyAlgorithm,
+        fulfillableObligations: fulfillableObligationFQNs,
       })
     );
   }

package/tdf3/src/tdf.ts

@@ -55,6 +55,7 @@ import { ZipReader, ZipWriter, keyMerge, concatUint8, buffToString } from './uti
 import { CentralDirectory } from './utils/zip-reader.js';
 import { ztdfSalt } from './crypto/salt.js';
 import { Payload } from './models/payload.js';
+import { getRequiredObligationFQNs } from '../../src/utils.js';
 
 // TODO: input validation on manifest JSON
 const DEFAULT_SEGMENT_SIZE = 1024 * 1024;
@@ -152,6 +153,7 @@ export type EncryptConfiguration = {
 };
 
 export type DecryptConfiguration = {
+  fulfillableObligations: string[];
   allowedKases?: string[];
   allowList?: OriginAllowList;
   authProvider: AuthProvider;
@@ -735,6 +737,7 @@ export function splitLookupTableFactory(
 type RewrapResponseData = {
   key: Uint8Array;
   metadata: Record<string, unknown>;
+  requiredObligations: string[];
 };
 
 async function unwrapKey({
@@ -745,6 +748,7 @@ async function unwrapKey({
   concurrencyLimit,
   cryptoService,
   wrappingKeyAlgorithm,
+  fulfillableObligations,
 }: {
   manifest: Manifest;
   allowedKases: OriginAllowList;
@@ -753,6 +757,7 @@ async function unwrapKey({
   dpopKeys: CryptoKeyPair;
   cryptoService: CryptoService;
   wrappingKeyAlgorithm?: KasPublicKeyAlgorithm;
+  fulfillableObligations: string[];
 }) {
   if (authProvider === undefined) {
     throw new ConfigurationError(
@@ -788,11 +793,14 @@ async function unwrapKey({
     const jwtPayload = { requestBody: requestBodyStr };
     const signedRequestToken = await reqSignature(jwtPayload, dpopKeys.privateKey);
 
-    const { entityWrappedKey, metadata, sessionPublicKey } = await fetchWrappedKey(
+    const rewrapResp = await fetchWrappedKey(
       url,
       signedRequestToken,
-      authProvider
+      authProvider,
+      fulfillableObligations
     );
+    const { entityWrappedKey, metadata, sessionPublicKey } = rewrapResp;
+    const requiredObligations = getRequiredObligationFQNs(rewrapResp);
 
     if (wrappingKeyAlgorithm === 'ec:secp256r1') {
       const serverEphemeralKey: CryptoKey = await pemPublicToCrypto(sessionPublicKey);
@@ -810,6 +818,7 @@ async function unwrapKey({
       return {
         key: new Uint8Array(dek),
         metadata,
+        requiredObligations,
       };
     }
     const key = Binary.fromArrayBuffer(entityWrappedKey);
@@ -821,6 +830,7 @@ async function unwrapKey({
     return {
       key: new Uint8Array(decryptedKeyBinary.asByteArray()),
       metadata,
+      requiredObligations,
     };
   }
 
@@ -850,12 +860,20 @@ async function unwrapKey({
     splitPromises[splitId] = () => anyPool(poolSize, anyPromises);
   }
   try {
-    const splitResults = await allPool(poolSize, splitPromises);
-    // Merge all the split keys
-    const reconstructedKey = keyMerge(splitResults.map((r) => r.key));
+    const rewrapResponseData = await allPool(poolSize, splitPromises);
+    const splitKeys = [];
+    const requiredObligations = new Set<string>();
+    for (const resp of rewrapResponseData) {
+      splitKeys.push(resp.key);
+      for (const requiredObligation of resp.requiredObligations) {
+        requiredObligations.add(requiredObligation.toLowerCase());
+      }
+    }
+    const reconstructedKey = keyMerge(splitKeys);
     return {
       reconstructedKeyBinary: Binary.fromArrayBuffer(reconstructedKey),
-      metadata: splitResults[0].metadata, // Use metadata from first split
+      metadata: rewrapResponseData[0].metadata, // Use metadata from first split
+      requiredObligations: [...requiredObligations],
     };
   } catch (e) {
     if (e instanceof AggregateError) {
@@ -1039,7 +1057,8 @@ export async function decryptStreamFrom(
     segmentSizeDefault,
     segments,
   } = manifest.encryptionInformation.integrityInformation;
-  const { metadata, reconstructedKeyBinary } = await unwrapKey({
+  const { metadata, reconstructedKeyBinary, requiredObligations } = await unwrapKey({
+    fulfillableObligations: cfg.fulfillableObligations,
     manifest,
     authProvider: cfg.authProvider,
     allowedKases: allowList,
@@ -1162,6 +1181,7 @@ export async function decryptStreamFrom(
 
   const outputStream = new DecoratedReadableStream(underlyingSource);
 
+  outputStream.requiredObligations = requiredObligations;
   outputStream.manifest = manifest;
   outputStream.metadata = metadata;
   return outputStream;