@opentdf/sdk 0.2.0-beta.1758 → 0.2.0-beta.1941

package/tdf3/src/client/index.ts

@@ -1,24 +1,20 @@
 import { v4 } from 'uuid';
 import {
   ZipReader,
-  fromBuffer,
-  fromDataSource,
   streamToBuffer,
-  type Chunker,
   keyMiddleware as defaultKeyMiddleware,
 } from '../utils/index.js';
 import { base64 } from '../../../src/encodings/index.js';
 import {
   buildKeyAccess,
-  EncryptConfiguration,
+  type EncryptConfiguration,
   fetchKasPublicKey,
   loadTDFStream,
-  unwrapHtml,
   validatePolicyObject,
   readStream,
-  wrapHtml,
   writeStream,
 } from '../tdf.js';
+import { unwrapHtml } from '../utils/unwrap.js';
 import { OIDCRefreshTokenProvider } from '../../../src/auth/oidc-refreshtoken-provider.js';
 import { OIDCExternalJwtProvider } from '../../../src/auth/oidc-externaljwt-provider.js';
 import { CryptoService } from '../crypto/declarations.js';
@@ -26,13 +22,13 @@ import { type AuthProvider, HttpRequest, withHeaders } from '../../../src/auth/a
 import { pemToCryptoPublicKey, rstrip, validateSecureUrl } from '../../../src/utils.js';
 
 import {
-  EncryptParams,
-  DecryptParams,
+  type EncryptParams,
+  type DecryptParams,
   type Scope,
-  DecryptStreamMiddleware,
-  EncryptKeyMiddleware,
-  EncryptStreamMiddleware,
-  SplitStep,
+  type DecryptStreamMiddleware,
+  type EncryptKeyMiddleware,
+  type EncryptStreamMiddleware,
+  type SplitStep,
 } from './builders.js';
 import { DecoratedReadableStream } from './DecoratedReadableStream.js';
 
@@ -42,25 +38,51 @@ import {
   type DecryptSource,
   EncryptParamsBuilder,
 } from './builders.js';
-import { KasPublicKeyInfo, OriginAllowList } from '../../../src/access.js';
+import {
+  type KasPublicKeyInfo,
+  keyAlgorithmToPublicKeyAlgorithm,
+  OriginAllowList,
+} from '../../../src/access.js';
 import { ConfigurationError } from '../../../src/errors.js';
 import { Binary } from '../binary.js';
 import { AesGcmCipher } from '../ciphers/aes-gcm-cipher.js';
 import { toCryptoKeyPair } from '../crypto/crypto-utils.js';
 import * as defaultCryptoService from '../crypto/index.js';
-import { type AttributeObject, type Policy, SplitKey } from '../models/index.js';
+import {
+  type AttributeObject,
+  type KeyAccessType,
+  type Policy,
+  SplitKey,
+} from '../models/index.js';
 import { plan } from '../../../src/policy/granter.js';
 import { attributeFQNsAsValues } from '../../../src/policy/api.js';
 import { type Value } from '../../../src/policy/attributes.js';
+import { type Chunker, fromBuffer, fromSource } from '../../../src/seekable.js';
 
 const GLOBAL_BYTE_LIMIT = 64 * 1000 * 1000 * 1000; // 64 GB, see WS-9363.
-const HTML_BYTE_LIMIT = 100 * 1000 * 1000; // 100 MB, see WS-9476.
 
 // No default config for now. Delegate to Virtru wrapper for endpoints.
 const defaultClientConfig = { oidcOrigin: '', cryptoService: defaultCryptoService };
 
 const getFirstTwoBytes = async (chunker: Chunker) => new TextDecoder().decode(await chunker(0, 2));
 
+// Convert a PEM string to a CryptoKey
+export const resolveKasInfo = async (
+  pem: string,
+  uri: string,
+  kid?: string
+): Promise<KasPublicKeyInfo> => {
+  const k: CryptoKey = await pemToCryptoPublicKey(pem);
+  const algorithm = keyAlgorithmToPublicKeyAlgorithm(k.algorithm);
+  return {
+    key: Promise.resolve(k),
+    publicKey: pem,
+    url: uri,
+    algorithm,
+    kid: kid,
+  };
+};
+
 const makeChunkable = async (source: DecryptSource) => {
   if (!source) {
     throw new ConfigurationError('invalid source');
@@ -82,7 +104,7 @@ const makeChunkable = async (source: DecryptSource) => {
       initialChunker = source.location;
       break;
     default:
-      initialChunker = await fromDataSource(source);
+      initialChunker = await fromSource(source);
   }
 
   const magic: string = await getFirstTwoBytes(initialChunker);
@@ -99,7 +121,7 @@ const makeChunkable = async (source: DecryptSource) => {
 
 export interface ClientConfig {
   cryptoService?: CryptoService;
-  organizationName?: string;
+  /// oauth client id; used to generate oauth authProvider
   clientId?: string;
   dpopEnabled?: boolean;
   dpopKeys?: Promise<CryptoKeyPair>;
@@ -217,7 +239,7 @@ export class Client {
    */
   readonly allowedKases: OriginAllowList;
 
-  readonly kasKeys: Record<string, Promise<KasPublicKeyInfo>> = {};
+  readonly kasKeys: Record<string, Promise<KasPublicKeyInfo>[]> = {};
 
   readonly easEndpoint?: string;
 
@@ -323,12 +345,9 @@ export class Client {
       dpopKeys: clientConfig.dpopKeys,
     });
     if (clientConfig.kasPublicKey) {
-      this.kasKeys[this.kasEndpoint] = Promise.resolve({
-        url: this.kasEndpoint,
-        algorithm: 'rsa:2048',
-        key: pemToCryptoPublicKey(clientConfig.kasPublicKey),
-        publicKey: clientConfig.kasPublicKey,
-      });
+      this.kasKeys[this.kasEndpoint] = [
+        resolveKasInfo(clientConfig.kasPublicKey, this.kasEndpoint),
+      ];
     }
   }
 
@@ -337,7 +356,6 @@ export class Client {
    *
    * @param scope dissem and attributes for constructing the policy
    * @param source source object of unencrypted data
-   * @param [asHtml] If we should wrap the TDF data in a self-opening HTML wrapper. Defaults to false
    * @param [autoconfigure] If we should use scope.attributes to configure KAOs
    * @param [metadata] Additional non-secret data to store with the TDF
    * @param [opts] Test only
@@ -348,28 +366,29 @@ export class Client {
    * @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
    */
-  async encrypt({
-    scope = { attributes: [], dissem: [] },
-    autoconfigure,
-    source,
-    asHtml = false,
-    metadata,
-    mimeType,
-    offline = true,
-    windowSize = DEFAULT_SEGMENT_SIZE,
-    keyMiddleware = defaultKeyMiddleware,
-    streamMiddleware = async (stream: DecoratedReadableStream) => stream,
-    splitPlan,
-    assertionConfigs = [],
-  }: EncryptParams): Promise<DecoratedReadableStream> {
-    if (!offline) {
+  async encrypt(opts: EncryptParams): Promise<DecoratedReadableStream> {
+    if (opts.offline === false) {
       throw new ConfigurationError('online mode not supported');
     }
+    if (opts.asHtml) {
+      throw new ConfigurationError('html mode not supported');
+    }
     const dpopKeys = await this.dpopKeys;
+    const {
+      autoconfigure,
+      metadata,
+      mimeType = 'unknown',
+      windowSize = DEFAULT_SEGMENT_SIZE,
+      keyMiddleware = defaultKeyMiddleware,
+      streamMiddleware = async (stream: DecoratedReadableStream) => stream,
+      wrappingKeyAlgorithm = 'rsa:2048',
+    } = opts;
+    const scope = opts.scope ?? { attributes: [], dissem: [] };
 
     const policyObject = asPolicy(scope);
     validatePolicyObject(policyObject);
 
+    let splitPlan = opts.splitPlan;
     if (!splitPlan && autoconfigure) {
       let avs: Value[] = scope.attributeValues ?? [];
       const fqns: string[] = scope.attributes
@@ -395,7 +414,7 @@ export class Client {
         }
       }
       if (
-        avs.length != scope.attributes?.length ||
+        avs.length != (scope.attributes?.length || 0) ||
         !avs.map(({ fqn }) => fqn).every((a) => fqns.indexOf(a) >= 0)
       ) {
         throw new ConfigurationError(
@@ -408,18 +427,9 @@ export class Client {
       splitPlan = detailedPlan.map((kat) => {
         const { kas, sid } = kat;
         if (kas?.publicKey?.cached?.keys && !(kas.uri in this.kasKeys)) {
-          const keys = kas.publicKey.cached.keys.filter(
-            ({ alg }) => alg == 'KAS_PUBLIC_KEY_ALG_ENUM_RSA_2048'
-          );
+          const keys = kas.publicKey.cached.keys;
           if (keys?.length) {
-            const key = keys[0];
-            this.kasKeys[kas.uri] = Promise.resolve({
-              key: pemToCryptoPublicKey(key.pem),
-              publicKey: key.pem,
-              url: kas.uri,
-              algorithm: 'rsa:2048',
-              kid: key.kid,
-            });
+            this.kasKeys[kas.uri] = keys.map((key) => resolveKasInfo(key.pem, kas.uri, key.kid));
           }
         }
         return { kas: kas.uri, sid };
@@ -428,17 +438,40 @@ export class Client {
 
     // TODO: Refactor underlying builder to remove some of this unnecessary config.
 
-    const byteLimit = asHtml ? HTML_BYTE_LIMIT : GLOBAL_BYTE_LIMIT;
+    const maxByteLimit = GLOBAL_BYTE_LIMIT;
+    const byteLimit =
+      opts.byteLimit === undefined || opts.byteLimit <= 0 || opts.byteLimit > maxByteLimit
+        ? maxByteLimit
+        : opts.byteLimit;
     const encryptionInformation = new SplitKey(new AesGcmCipher(this.cryptoService));
-    const splits: SplitStep[] = splitPlan?.length ? splitPlan : [{ kas: this.kasEndpoint }];
+    const splits: SplitStep[] = splitPlan?.length
+      ? splitPlan
+      : [{ kas: opts.defaultKASEndpoint ?? this.kasEndpoint }];
     encryptionInformation.keyAccess = await Promise.all(
       splits.map(async ({ kas, sid }) => {
         if (!(kas in this.kasKeys)) {
-          this.kasKeys[kas] = fetchKasPublicKey(kas);
+          this.kasKeys[kas] = [fetchKasPublicKey(kas, wrappingKeyAlgorithm)];
+        }
+        const kasPublicKey = await Promise.any(this.kasKeys[kas]);
+        if (kasPublicKey.algorithm !== wrappingKeyAlgorithm) {
+          console.warn(
+            `Mismatched wrapping key algorithm: [${kasPublicKey.algorithm}] is not requested type, [${wrappingKeyAlgorithm}]`
+          );
+        }
+        let type: KeyAccessType;
+        switch (kasPublicKey.algorithm) {
+          case 'rsa:2048':
+            type = 'wrapped';
+            break;
+          case 'ec:secp256r1':
+            type = 'ec-wrapped';
+            break;
+          default:
+            throw new ConfigurationError(`Unsupported algorithm ${kasPublicKey.algorithm}`);
         }
-        const kasPublicKey = await this.kasKeys[kas];
         return buildKeyAccess({
-          type: offline ? 'wrapped' : 'remote',
+          alg: kasPublicKey.algorithm,
+          type,
           url: kasPublicKey.url,
           kid: kasPublicKey.kid,
           publicKey: kasPublicKey.publicKey,
@@ -457,34 +490,17 @@ export class Client {
       segmentSizeDefault: windowSize,
       integrityAlgorithm: 'HS256',
       segmentIntegrityAlgorithm: 'GMAC',
-      contentStream: source,
+      contentStream: opts.source,
       mimeType,
       policy: policyObject,
       authProvider: this.authProvider,
       progressHandler: this.clientConfig.progressHandler,
       keyForEncryption,
       keyForManifest,
-      assertionConfigs,
+      assertionConfigs: opts.assertionConfigs,
     };
 
-    const stream = await (streamMiddleware as EncryptStreamMiddleware)(await writeStream(ecfg));
-
-    if (!asHtml) {
-      return stream;
-    }
-
-    // Wrap if it's html.
-    if (!stream.manifest) {
-      throw new Error('internal: missing manifest in encrypt function');
-    }
-    const htmlBuf = wrapHtml(await stream.toBuffer(), stream.manifest, this.readerUrl ?? '');
-
-    return new DecoratedReadableStream({
-      pull(controller: ReadableStreamDefaultController) {
-        controller.enqueue(htmlBuf);
-        controller.close();
-      },
-    });
+    return (streamMiddleware as EncryptStreamMiddleware)(await writeStream(ecfg));
   }
 
   /**
@@ -500,23 +516,28 @@ export class Client {
    */
   async decrypt({
     source,
+    allowList,
     keyMiddleware = async (key: Binary) => key,
     streamMiddleware = async (stream: DecoratedReadableStream) => stream,
     assertionVerificationKeys,
     noVerifyAssertions,
     concurrencyLimit = 1,
+    wrappingKeyAlgorithm,
   }: DecryptParams): Promise<DecoratedReadableStream> {
     const dpopKeys = await this.dpopKeys;
     if (!this.authProvider) {
       throw new ConfigurationError('AuthProvider missing');
     }
     const chunker = await makeChunkable(source);
+    if (!allowList) {
+      allowList = this.allowedKases;
+    }
 
     // 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)(
       await readStream({
-        allowList: this.allowedKases,
+        allowList,
         authProvider: this.authProvider,
         chunker,
         concurrencyLimit,
@@ -527,6 +548,7 @@ export class Client {
         progressHandler: this.clientConfig.progressHandler,
         assertionVerificationKeys,
         noVerifyAssertions,
+        wrappingKeyAlgorithm,
       })
     );
   }
@@ -558,11 +580,4 @@ export class Client {
 
 export type { AuthProvider };
 
-export {
-  DecryptParamsBuilder,
-  DecryptSource,
-  EncryptParamsBuilder,
-  HttpRequest,
-  fromDataSource,
-  withHeaders,
-};
+export { DecryptParamsBuilder, DecryptSource, EncryptParamsBuilder, HttpRequest, withHeaders };

package/tdf3/src/index.ts

@@ -1,4 +1,4 @@
 export * as Client from './client/index.js';
 export { Client as TDF3Client } from './client/index.js';
 export * as Errors from '../../src/errors.js';
-export { version, clientType } from './version.js';
+export { clientType, tdfSpecVersion, version } from '../../src/version.js';

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

@@ -78,7 +78,7 @@ export class SplitKey {
   }
 
   async getKeyAccessObjects(policy: Policy, keyInfo: KeyInfo): Promise<KeyAccessObject[]> {
-    const splitIds = [...new Set(this.keyAccess.map(({ sid }) => sid))].sort((a, b) =>
+    const splitIds = [...new Set(this.keyAccess.map(({ sid }) => sid))].sort((a = '', b = '') =>
       a.localeCompare(b)
     );
     const unwrappedKeySplitBuffers = await keySplit(
@@ -93,7 +93,7 @@ export class SplitKey {
     const keyAccessObjects = [];
     for (const item of this.keyAccess) {
       // use the key split to encrypt metadata for each key access object
-      const unwrappedKeySplitBuffer = splitsByName[item.sid];
+      const unwrappedKeySplitBuffer = splitsByName[item.sid || ''];
       const unwrappedKeySplitBinary = Binary.fromArrayBuffer(unwrappedKeySplitBuffer.buffer);
 
       const metadata = item.metadata || '';

package/tdf3/src/models/key-access.ts

@@ -1,16 +1,19 @@
-import { Binary } from '../binary.js';
 import { base64, hex } from '../../../src/encodings/index.js';
+import { generateRandomNumber } from '../../../src/nanotdf-crypto/generateRandomNumber.js';
+import { keyAgreement } from '../../../src/nanotdf-crypto/keyAgreement.js';
+import { pemPublicToCrypto } from '../../../src/nanotdf-crypto/pemPublicToCrypto.js';
+import { cryptoPublicToPem } from '../../../src/utils.js';
+import { Binary } from '../binary.js';
 import * as cryptoService from '../crypto/index.js';
 import { Policy } from './policy.js';
 
-export type KeyAccessType = 'remote' | 'wrapped';
+export type KeyAccessType = 'remote' | 'wrapped' | 'ec-wrapped';
 
-export function isRemote(keyAccessJSON: KeyAccess | KeyAccessObject): boolean {
-  return keyAccessJSON.type === 'remote';
-}
+export const schemaVersion = '1.0';
 
-export class Wrapped {
-  readonly type = 'wrapped';
+export class ECWrapped {
+  readonly type = 'ec-wrapped';
+  readonly ephemeralKeyPair: Promise<CryptoKeyPair>;
   keyAccessObject?: KeyAccessObject;
 
   constructor(
@@ -18,60 +21,78 @@ export class Wrapped {
     public readonly kid: string | undefined,
     public readonly publicKey: string,
     public readonly metadata: unknown,
-    public readonly sid: string
-  ) {}
+    public readonly sid?: string
+  ) {
+    this.ephemeralKeyPair = crypto.subtle.generateKey(
+      {
+        name: 'ECDH',
+        namedCurve: 'P-256',
+      },
+      false,
+      ['deriveBits', 'deriveKey']
+    );
+  }
 
   async write(
     policy: Policy,
-    keyBuffer: Uint8Array,
+    dek: Uint8Array,
     encryptedMetadataStr: string
   ): Promise<KeyAccessObject> {
     const policyStr = JSON.stringify(policy);
-    const unwrappedKeyBinary = Binary.fromArrayBuffer(keyBuffer.buffer);
-    const wrappedKeyBinary = await cryptoService.encryptWithPublicKey(
-      unwrappedKeyBinary,
-      this.publicKey
-    );
+    const [ek, clientPublicKey] = await Promise.all([
+      this.ephemeralKeyPair,
+      pemPublicToCrypto(this.publicKey),
+    ]);
+    const kek = await keyAgreement(ek.privateKey, clientPublicKey, {
+      hkdfSalt: new TextEncoder().encode('salt'),
+      hkdfHash: 'SHA-256',
+    });
+    const iv = generateRandomNumber(12);
+    const cek = await crypto.subtle.encrypt({ name: 'AES-GCM', iv, tagLength: 128 }, kek, dek);
+    const entityWrappedKey = new Uint8Array(iv.length + cek.byteLength);
+    entityWrappedKey.set(iv);
+    entityWrappedKey.set(new Uint8Array(cek), iv.length);
 
     const policyBinding = await cryptoService.hmac(
-      hex.encodeArrayBuffer(keyBuffer),
+      hex.encodeArrayBuffer(dek),
       base64.encode(policyStr)
     );
 
-    this.keyAccessObject = {
-      type: 'wrapped',
+    const ephemeralPublicKeyPEM = await cryptoPublicToPem(ek.publicKey);
+    const kao: KeyAccessObject = {
+      type: 'ec-wrapped',
       url: this.url,
       protocol: 'kas',
-      wrappedKey: base64.encode(wrappedKeyBinary.asString()),
+      wrappedKey: base64.encodeArrayBuffer(entityWrappedKey),
       encryptedMetadata: base64.encode(encryptedMetadataStr),
       policyBinding: {
         alg: 'HS256',
         hash: base64.encode(policyBinding),
       },
+      schemaVersion,
+      ephemeralPublicKey: ephemeralPublicKeyPEM,
     };
     if (this.kid) {
-      this.keyAccessObject.kid = this.kid;
+      kao.kid = this.kid;
     }
     if (this.sid?.length) {
-      this.keyAccessObject.sid = this.sid;
+      kao.sid = this.sid;
     }
-
-    return this.keyAccessObject;
+    this.keyAccessObject = kao;
+    return kao;
   }
 }
 
-export class Remote {
-  readonly type = 'remote';
+export class Wrapped {
+  readonly type = 'wrapped';
   keyAccessObject?: KeyAccessObject;
-  wrappedKey?: string;
-  policyBinding?: string;
 
   constructor(
     public readonly url: string,
     public readonly kid: string | undefined,
     public readonly publicKey: string,
     public readonly metadata: unknown,
-    public readonly sid: string
+    public readonly sid?: string
   ) {}
 
   async write(
@@ -80,49 +101,110 @@ export class Remote {
     encryptedMetadataStr: string
   ): Promise<KeyAccessObject> {
     const policyStr = JSON.stringify(policy);
-    const policyBinding = await cryptoService.hmac(
-      hex.encodeArrayBuffer(keyBuffer),
-      base64.encode(policyStr)
-    );
     const unwrappedKeyBinary = Binary.fromArrayBuffer(keyBuffer.buffer);
     const wrappedKeyBinary = await cryptoService.encryptWithPublicKey(
       unwrappedKeyBinary,
       this.publicKey
     );
 
-    // this.wrappedKey = wrappedKeyBinary.asBuffer().toString('hex');
-    this.wrappedKey = base64.encode(wrappedKeyBinary.asString());
+    const policyBinding = await cryptoService.hmac(
+      hex.encodeArrayBuffer(keyBuffer),
+      base64.encode(policyStr)
+    );
 
     this.keyAccessObject = {
-      type: 'remote',
+      type: 'wrapped',
       url: this.url,
       protocol: 'kas',
-      wrappedKey: this.wrappedKey,
+      wrappedKey: base64.encode(wrappedKeyBinary.asString()),
       encryptedMetadata: base64.encode(encryptedMetadataStr),
       policyBinding: {
         alg: 'HS256',
         hash: base64.encode(policyBinding),
       },
+      schemaVersion,
     };
     if (this.kid) {
       this.keyAccessObject.kid = this.kid;
     }
+    if (this.sid?.length) {
+      this.keyAccessObject.sid = this.sid;
+    }
+
     return this.keyAccessObject;
   }
 }
 
-export type KeyAccess = Remote | Wrapped;
+export type KeyAccess = ECWrapped | Wrapped;
 
+/**
+ * A KeyAccess object stores all information about how an object key OR one key split is stored.
+ */
 export type KeyAccessObject = {
-  sid?: string;
+  /**
+   * Specifies how the key is stored. Possible Values:
+   * **wrapped**: The wrapped key is stored as part of the manifest.
+   * **remote**: [Unsupported] The wrapped key (see below) is stored remotely and is thus not part of the final TDF manifest.
+   */
   type: KeyAccessType;
+
+  /**
+   * A key split (or share) identifier.
+   * To allow sharing a key across several access domains,
+   * the KAO supports a 'Split Identifier'.
+   * To reconstruct such a key when encryptionInformation type is 'split',
+   * use the xor operation to combine one of each separate sid.
+   */
+  sid?: string;
+
+  /**
+   * A locator for a Key Access service capable of granting access to the wrapped key.
+   */
   url: string;
+
+  /**
+   * Additional information for the Key Access service to identify how to unwrap the key.
+   */
   kid?: string;
+
+  /**
+   * The protocol used to access the key.
+   */
   protocol: 'kas';
+
+  /**
+   * The symmetric key used to encrypt the payload.
+   * It is encrypted using the public key of the KAS,
+   * then base64 encoded.
+   */
   wrappedKey?: string;
+
+  /**
+   * An object that contains a keyed hash that will provide cryptographic integrity on the policy object,
+   * such that it cannot be modified or copied to another TDF
+   * without invalidating the binding.
+   * Specifically, you would have to have access to the key in order to overwrite the policy.
+   */
   policyBinding?: {
     alg: string;
     hash: string;
   };
+
+  /**
+   * Metadata associated with the TDF and the request.
+   * The contents of the metadata are freeform,
+   * and are used to pass information from the client to the KAS.
+   * The metadata stored here should not be used for primary access decisions.
+   */
   encryptedMetadata?: string;
+
+  /**
+   * Version information for the KAO format.
+   */
+  schemaVersion?: string;
+
+  /**
+   * PEM encoded ephemeral public key, if wrapped with a KAS EC key.
+   */
+  ephemeralPublicKey?: string;
 };

package/tdf3/src/models/manifest.ts

@@ -6,4 +6,7 @@ export type Manifest = {
   payload: Payload;
   encryptionInformation: EncryptionInformation;
   assertions: Assertion[];
+  schemaVersion: string;
+  // Deprecated
+  tdf_spec_version?: string;
 };

package/tdf3/src/models/policy.ts

@@ -9,7 +9,6 @@ export type PolicyBody = {
 };
 
 export type Policy = {
-  tdf_spec_version?: string;
   uuid?: string;
   body?: PolicyBody;
 };