@opentdf/sdk 0.2.0 → 0.3.0-beta.2050

package/src/opentdf.ts

@@ -6,7 +6,7 @@ import NanoTDF from './nanotdf/NanoTDF.js';
 import decryptNanoTDF from './nanotdf/decrypt.js';
 import Client from './nanotdf/Client.js';
 import Header from './nanotdf/models/Header.js';
-import { fromSource, sourceToStream, type Source } from './seekable.js';
+import { Chunker, fromSource, sourceToStream, type Source } from './seekable.js';
 import { Client as TDF3Client } from '../tdf3/src/client/index.js';
 import {
   type Assertion,
@@ -22,7 +22,15 @@ import {
   type EncryptionInformation,
 } from '../tdf3/src/models/encryption-information.js';
 import { type KeyAccessObject } from '../tdf3/src/models/key-access.js';
-import { type IntegrityAlgorithm } from '../tdf3/src/tdf.js';
+import {
+  decryptStreamFrom,
+  InspectedTDFOverview,
+  loadTDFStream,
+  type IntegrityAlgorithm,
+} from '../tdf3/src/tdf.js';
+import { base64 } from './encodings/index.js';
+import PolicyType from './nanotdf/enum/PolicyTypeEnum.js';
+import { Policy } from '../tdf3/src/models/policy.js';
 
 export {
   type Assertion,
@@ -248,6 +256,30 @@ export class RewrapCache {
   }
 }
 
+/**
+ * A TDF reader that can decrypt and inspect a TDF file.
+ */
+export type TDFReader = {
+  /**
+   * Decrypt the payload.
+   */
+  decrypt: () => Promise<DecoratedStream>;
+  /**
+   * Mark this reader as closed and release any resources, such as open files.
+   */
+  close: () => Promise<void>;
+
+  /**
+   * Only present on ZTDF files
+   */
+  manifest: () => Promise<Manifest>;
+
+  /**
+   * @returns Any data attributes found in the policy. Currently only works for plain text, embedded policies (not remote or encrypted policies)
+   */
+  attributes: () => Promise<string[]>;
+};
+
 // SDK for dealing with OpenTDF data and policy services.
 export class OpenTDF {
   // Configuration service and more is at this URL/connectRPC endpoint
@@ -260,7 +292,7 @@ export class OpenTDF {
 
   // Header cache for reading nanotdf collections
   private readonly rewrapCache: RewrapCache;
-  private tdf3Client: TDF3Client;
+  readonly tdf3Client: TDF3Client;
 
   constructor({
     authProvider,
@@ -311,7 +343,9 @@ 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): Promise<NanoTDFCollection> {
+  async createNanoTDFCollection(
+    opts: CreateNanoTDFCollectionOptions
+  ): Promise<NanoTDFCollectionWriter> {
     opts = { ...this.defaultCreateOptions, ...opts };
     return new Collection(this.authProvider, opts);
   }
@@ -340,66 +374,227 @@ export class OpenTDF {
   }
 
   /**
-   * Decrypts a nanotdf object. Optionally, stores the collection header and its DEK.
-   * @param ciphertext
+   * Opens a TDF file for inspection and decryption.
+   * @param opts the file to open, and any appropriate configuration options
+   * @returns
    */
-  async read(opts: ReadOptions): Promise<DecoratedStream> {
+  open(opts: ReadOptions): TDFReader {
     opts = { ...this.defaultReadOptions, ...opts };
-    const chunker = await fromSource(opts.source);
+    return new UnknownTypeReader(this, opts, this.rewrapCache);
+  }
+
+  async read(opts: ReadOptions): Promise<DecoratedStream> {
+    const reader = this.open(opts);
+    return reader.decrypt();
+  }
+
+  close() {
+    this.rewrapCache.close();
+  }
+}
+
+class UnknownTypeReader {
+  delegate: Promise<TDFReader>;
+  state: 'init' | 'resolving' | 'loaded' | 'decrypting' | 'closing' | 'done' | 'error' = 'init';
+  constructor(
+    readonly outer: OpenTDF,
+    readonly opts: ReadOptions,
+    private readonly rewrapCache: RewrapCache
+  ) {
+    this.delegate = this.resolveType();
+  }
+
+  async resolveType(): Promise<TDFReader> {
+    if (this.state === 'done') {
+      throw new ConfigurationError('reader is closed');
+    }
+    this.state = 'resolving';
+    const chunker = await fromSource(this.opts.source);
     const prefix = await chunker(0, 3);
-    // switch for prefix, if starts with `PK` in ascii, or `L1L` in ascii:
     if (prefix[0] === 0x50 && prefix[1] === 0x4b) {
-      const allowList = new OriginAllowList(opts.allowedKASEndpoints ?? [], opts.ignoreAllowlist);
-      const oldStream = await this.tdf3Client.decrypt({
-        source: opts.source,
-        allowList,
-        assertionVerificationKeys: opts.assertionVerificationKeys,
-        noVerifyAssertions: opts.noVerify,
-        wrappingKeyAlgorithm: opts.wrappingKeyAlgorithm,
-      });
-      const stream: DecoratedStream = oldStream.stream;
-      stream.metadata = Promise.resolve(oldStream.metadata);
-      return stream;
+      this.state = 'loaded';
+      return new ZTDFReader(this.outer.tdf3Client, this.opts, chunker);
     } else if (prefix[0] === 0x4c && prefix[1] === 0x31 && prefix[2] === 0x4c) {
-      const ciphertext = await chunker();
-      const nanotdf = NanoTDF.from(ciphertext);
-      const cachedDEK = this.rewrapCache.get(nanotdf.header.ephemeralPublicKey);
-      if (cachedDEK) {
-        const r: DecoratedStream = await streamify(decryptNanoTDF(cachedDEK, nanotdf));
-        r.header = nanotdf.header;
-        return r;
-      }
-      const nc = new Client({
-        allowedKases: opts.allowedKASEndpoints,
-        authProvider: this.authProvider,
-        ignoreAllowList: opts.ignoreAllowlist,
-        dpopEnabled: this.dpopEnabled,
-        dpopKeys: this.dpopKeys,
-        kasEndpoint: opts.allowedKASEndpoints?.[0] || 'https://disallow.all.invalid',
-      });
-      // 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(
-        nanotdf.header.toBuffer(),
-        nanotdf.header.getKasRewrapUrl(),
-        nanotdf.header.magicNumberVersion,
-        version
-      );
-      if (!dek) {
-        // These should have thrown already.
-        throw new Error('internal: key rewrap failure');
+      this.state = 'loaded';
+      return new NanoTDFReader(this.outer, this.opts, chunker, this.rewrapCache);
+    }
+    this.state = 'done';
+    throw new InvalidFileError(`unsupported format; prefix not recognized ${prefix}`);
+  }
+
+  async decrypt(): Promise<DecoratedStream> {
+    const actual = await this.delegate;
+    return actual.decrypt();
+  }
+
+  async attributes(): Promise<string[]> {
+    const actual = await this.delegate;
+    return actual.attributes();
+  }
+
+  async manifest(): Promise<Manifest> {
+    const actual = await this.delegate;
+    return actual.manifest();
+  }
+
+  async close() {
+    if (this.state === 'done') {
+      return;
+    }
+    if (this.state === 'init') {
+      // delegate resolve never started
+      this.state = 'done';
+      return;
+    }
+    this.state = 'closing';
+    const actual = await this.delegate;
+    return actual.close().then(() => {
+      this.state = 'done';
+    });
+  }
+}
+
+class NanoTDFReader {
+  container: Promise<NanoTDF>;
+  constructor(
+    readonly outer: OpenTDF,
+    readonly opts: ReadOptions,
+    readonly chunker: Chunker,
+    private readonly rewrapCache: RewrapCache
+  ) {
+    // lazily load the container
+    this.container = new Promise(async (resolve, reject) => {
+      try {
+        const ciphertext = await chunker();
+        const nanotdf = NanoTDF.from(ciphertext);
+        resolve(nanotdf);
+      } catch (e) {
+        reject(e);
       }
-      this.rewrapCache.set(nanotdf.header.ephemeralPublicKey, dek);
-      const r: DecoratedStream = await streamify(decryptNanoTDF(dek, nanotdf));
+    });
+  }
+
+  async decrypt(): Promise<DecoratedStream> {
+    const nanotdf = await this.container;
+    const cachedDEK = this.rewrapCache.get(nanotdf.header.ephemeralPublicKey);
+    if (cachedDEK) {
+      const r: DecoratedStream = await streamify(decryptNanoTDF(cachedDEK, nanotdf));
       r.header = nanotdf.header;
       return r;
     }
-    throw new InvalidFileError(`unsupported format; prefix not recognized ${prefix}`);
+    const nc = new Client({
+      allowedKases: this.opts.allowedKASEndpoints,
+      authProvider: this.outer.authProvider,
+      ignoreAllowList: this.opts.ignoreAllowlist,
+      dpopEnabled: this.outer.dpopEnabled,
+      dpopKeys: this.outer.dpopKeys,
+      kasEndpoint: this.opts.allowedKASEndpoints?.[0] || 'https://disallow.all.invalid',
+    });
+    // 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(
+      nanotdf.header.toBuffer(),
+      nanotdf.header.getKasRewrapUrl(),
+      nanotdf.header.magicNumberVersion,
+      version
+    );
+    if (!dek) {
+      // These should have thrown already.
+      throw new Error('internal: key rewrap failure');
+    }
+    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
+    r.header = nanotdf.header;
+    return r;
   }
 
-  close() {
-    this.rewrapCache.close();
+  async close() {}
+
+  async manifest(): Promise<Manifest> {
+    return {} as Manifest;
+  }
+
+  async attributes(): Promise<string[]> {
+    const nanotdf = await this.container;
+    if (!nanotdf.header.policy?.content) {
+      return [];
+    }
+    if (nanotdf.header.policy.type !== PolicyType.EmbeddedText) {
+      throw new Error('unsupported policy type');
+    }
+    const policyString = new TextDecoder().decode(nanotdf.header.policy.content);
+    const policy = JSON.parse(policyString) as Policy;
+    return policy?.body?.dataAttributes.map((a) => a.attribute) || [];
+  }
+}
+
+class ZTDFReader {
+  overview: Promise<InspectedTDFOverview>;
+  constructor(
+    readonly client: TDF3Client,
+    readonly opts: ReadOptions,
+    readonly source: Chunker
+  ) {
+    this.overview = loadTDFStream(source);
+  }
+
+  async decrypt(): Promise<DecoratedStream> {
+    const {
+      assertionVerificationKeys,
+      noVerify: noVerifyAssertions,
+      wrappingKeyAlgorithm,
+    } = this.opts;
+    const allowList = new OriginAllowList(
+      this.opts.allowedKASEndpoints ?? [],
+      this.opts.ignoreAllowlist
+    );
+    const dpopKeys = await this.client.dpopKeys;
+
+    const { authProvider, cryptoService } = this.client;
+    if (!authProvider) {
+      throw new ConfigurationError('authProvider is required');
+    }
+
+    const overview = await this.overview;
+    const oldStream = await decryptStreamFrom(
+      {
+        allowList,
+        authProvider,
+        chunker: this.source,
+        concurrencyLimit: 1,
+        cryptoService,
+        dpopKeys,
+        fileStreamServiceWorker: this.client.clientConfig.fileStreamServiceWorker,
+        keyMiddleware: async (k) => k,
+        progressHandler: this.client.clientConfig.progressHandler,
+        assertionVerificationKeys,
+        noVerifyAssertions,
+        wrappingKeyAlgorithm,
+      },
+      overview
+    );
+    const stream: DecoratedStream = oldStream.stream;
+    stream.manifest = Promise.resolve(overview.manifest);
+    stream.metadata = Promise.resolve(oldStream.metadata);
+    return stream;
+  }
+
+  async close() {
+    // TODO figure out how to close a chunker, if we want to.
+  }
+
+  async manifest(): Promise<Manifest> {
+    const overview = await this.overview;
+    return overview.manifest;
+  }
+
+  async attributes(): Promise<string[]> {
+    const manifest = await this.manifest();
+    const policyJSON = base64.decode(manifest.encryptionInformation.policy);
+    const policy = JSON.parse(policyJSON) as Policy;
+    return policy?.body?.dataAttributes.map((a) => a.attribute) || [];
   }
 }
 
@@ -415,7 +610,7 @@ async function streamify(ab: Promise<ArrayBuffer>): Promise<ReadableStream<Uint8
   return stream;
 }
 
-export type NanoTDFCollection = {
+export type NanoTDFCollectionWriter = {
   encrypt: (source: Source) => Promise<ReadableStream<Uint8Array>>;
   close: () => Promise<void>;
 };

package/src/tdf/Policy.ts

@@ -1,7 +1,9 @@
-import { type AttributeObject } from './AttributeObject.js';
 import { v4 as uuid } from 'uuid';
 
-export class Policy {
+import { type AttributeObject } from '../../tdf3/src/models/attribute.js';
+import { type Policy } from '../../tdf3/src/models/policy.js';
+
+export class PolicyBuilder {
   static CURRENT_VERSION = '1.1.0';
 
   private uuidStr = uuid();
@@ -33,18 +35,22 @@ export class Policy {
     this.dataAttributesList.push(attribute);
   }
 
+  toPolicy(): Policy {
+    return {
+      uuid: this.uuidStr,
+      body: {
+        dataAttributes: this.dataAttributesList,
+        dissem: this.dissemList,
+      },
+    };
+  }
+
   /**
    * Returns the JSON string of Policy object
    *
    * @return {string} [The constructed Policy object as JSON string]
    */
   toJSON(): string {
-    return JSON.stringify({
-      uuid: this.uuidStr,
-      body: {
-        dataAttributes: this.dataAttributesList,
-        dissem: this.dissemList,
-      },
-    });
+    return JSON.stringify(this.toPolicy());
   }
 }

package/src/version.ts

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

package/tdf3/index.ts

@@ -90,7 +90,8 @@ export {
   type DecoratedStream,
   type Keys,
   type OpenTDFOptions,
-  type NanoTDFCollection,
+  type NanoTDFCollectionWriter,
   type ReadOptions,
+  type TDFReader,
   OpenTDF,
 } from '../src/opentdf.js';

package/tdf3/src/assertions.ts

@@ -1,5 +1,5 @@
 import { canonicalizeEx } from 'json-canonicalize';
-import { type KeyLike, SignJWT, jwtVerify } from 'jose';
+import { SignJWT, jwtVerify } from 'jose';
 import { base64, hex } from '../../src/encodings/index.js';
 import { ConfigurationError, IntegrityError, InvalidFileError } from '../../src/errors.js';
 
@@ -185,7 +185,7 @@ export async function CreateAssertion(
 
 export type AssertionKey = {
   alg: AssertionKeyAlg;
-  key: KeyLike | Uint8Array;
+  key: CryptoKey | Uint8Array;
 };
 
 // AssertionConfig is a shadow of Assertion with the addition of the signing key.

package/tdf3/src/crypto/salt.ts

@@ -0,0 +1,11 @@
+const generateSalt = async () => {
+  const encoder = new TextEncoder();
+  const data = encoder.encode('TDF');
+
+  // Generate hash
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+
+  return new Uint8Array(hashBuffer);
+};
+
+export const ztdfSalt = generateSalt();

package/tdf3/src/models/attribute.ts

@@ -0,0 +1,26 @@
+/**
+ * Information about a data or entity attribute, its meaning and interpretation.
+ * While usually we just refer to an attribute by its URL,
+ * we often need to store additional information about it,
+ * for display or analysis.
+ */
+export type AttributeObject = {
+  // The fully qualified name of the attribute, generally a URL
+  attribute: string;
+  // Optional descriptive name of the attribute
+  displayName?: string;
+  // Indicates a default attribute, usually for all policies associated with a KAS
+  isDefault?: boolean;
+
+  // Optional: A cryptographically bound version of the attribute. Deprecated: use a JWS with this as the payload.
+  jwt?: string;
+
+  // A KAS that is associated with the attribute.
+  kasUrl?: string;
+
+  // The preferred public key for the attribute
+  kid?: string;
+
+  // The public key value for the attribute
+  pubKey?: string;
+};

package/tdf3/src/models/index.ts

@@ -1,4 +1,4 @@
-export * from './attribute-set.js';
+export * from './attribute.js';
 export * from './encryption-information.js';
 export * from './key-access.js';
 export * from './manifest.js';

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

@@ -5,6 +5,7 @@ import { pemPublicToCrypto } from '../../../src/nanotdf-crypto/pemPublicToCrypto
 import { cryptoPublicToPem } from '../../../src/utils.js';
 import { Binary } from '../binary.js';
 import * as cryptoService from '../crypto/index.js';
+import { ztdfSalt } from '../crypto/salt.js';
 import { Policy } from './policy.js';
 
 export type KeyAccessType = 'remote' | 'wrapped' | 'ec-wrapped';
@@ -44,7 +45,7 @@ export class ECWrapped {
       pemPublicToCrypto(this.publicKey),
     ]);
     const kek = await keyAgreement(ek.privateKey, clientPublicKey, {
-      hkdfSalt: new TextEncoder().encode('salt'),
+      hkdfSalt: await ztdfSalt,
       hkdfHash: 'SHA-256',
     });
     const iv = generateRandomNumber(12);

package/tdf3/src/models/payload.ts

@@ -3,4 +3,5 @@ export type Payload = {
   url: string; // "0.payload"
   protocol: string; // "zip"
   isEncrypted: boolean; // true
+  mimeType?: string; // e.g. "text/plain"
 };

package/tdf3/src/models/policy.ts

@@ -1,5 +1,5 @@
 import { ConfigurationError } from '../../../src/errors.js';
-import { AttributeObject } from './attribute-set.js';
+import { type AttributeObject } from './attribute.js';
 
 export const CURRENT_VERSION = '1.1.0';
 

package/tdf3/src/tdf.ts

@@ -24,7 +24,6 @@ import { generateKeyPair } from '../../src/nanotdf-crypto/generateKeyPair.js';
 import { keyAgreement } from '../../src/nanotdf-crypto/keyAgreement.js';
 import { pemPublicToCrypto } from '../../src/nanotdf-crypto/pemPublicToCrypto.js';
 import { type Chunker } from '../../src/seekable.js';
-import { PolicyObject } from '../../src/tdf/PolicyObject.js';
 import { tdfSpecVersion } from '../../src/version.js';
 import { AssertionConfig, AssertionKey, AssertionVerificationKeys } from './assertions.js';
 import * as assertions from './assertions.js';
@@ -54,6 +53,8 @@ import {
 import { unsigned } from './utils/buffer-crc32.js';
 import { ZipReader, ZipWriter, keyMerge, concatUint8 } from './utils/index.js';
 import { CentralDirectory } from './utils/zip-reader.js';
+import { ztdfSalt } from './crypto/salt.js';
+import { Payload } from './models/payload.js';
 
 // TODO: input validation on manifest JSON
 const DEFAULT_SEGMENT_SIZE = 1024 * 1024;
@@ -72,12 +73,7 @@ export type EncryptionOptions = {
 
 type KeyMiddleware = DecryptParams['keyMiddleware'];
 
-export type Metadata = {
-  connectOptions?: {
-    testUrl: string;
-  };
-  policyObject?: PolicyObject;
-};
+export type Metadata = unknown;
 
 export type BuildKeyAccess = {
   type: KeyAccessType;
@@ -291,7 +287,7 @@ async function _generateManifest(
   mimeType: string | undefined
 ): Promise<Manifest> {
   // (maybe) Fields are quoted to avoid renaming
-  const payload = {
+  const payload: Payload = {
     type: 'reference',
     url: '0.payload',
     protocol: 'zip',
@@ -596,10 +592,14 @@ export async function writeStream(cfg: EncryptConfiguration): Promise<DecoratedR
   }
 }
 
+export type InspectedTDFOverview = {
+  manifest: Manifest;
+  zipReader: ZipReader;
+  centralDirectory: CentralDirectory[];
+};
+
 // load the TDF as a stream in memory, for further use in reading and key syncing
-export async function loadTDFStream(
-  chunker: Chunker
-): Promise<{ manifest: Manifest; zipReader: ZipReader; centralDirectory: CentralDirectory[] }> {
+export async function loadTDFStream(chunker: Chunker): Promise<InspectedTDFOverview> {
   const zipReader = new ZipReader(chunker);
   const centralDirectory = await zipReader.getCentralDirectory();
   const manifest = await zipReader.getManifest(centralDirectory, '0.manifest.json');
@@ -707,7 +707,7 @@ async function unwrapKey({
       const serverEphemeralKey: CryptoKey = await pemPublicToCrypto(sessionPublicKey);
       const ekr = ephemeralEncryptionKeysRaw as CryptoKeyPair;
       const kek = await keyAgreement(ekr.privateKey, serverEphemeralKey, {
-        hkdfSalt: new TextEncoder().encode('salt'),
+        hkdfSalt: await ztdfSalt,
         hkdfHash: 'SHA-256',
       });
       const wrappedKeyAndNonce = base64.decodeArrayBuffer(entityWrappedKey);
@@ -919,6 +919,14 @@ export async function sliceAndDecrypt({
 }
 
 export async function readStream(cfg: DecryptConfiguration) {
+  const overview = await loadTDFStream(cfg.chunker);
+  return decryptStreamFrom(cfg, overview);
+}
+
+export async function decryptStreamFrom(
+  cfg: DecryptConfiguration,
+  { manifest, zipReader, centralDirectory }: InspectedTDFOverview
+) {
   let { allowList } = cfg;
   if (!allowList) {
     if (!cfg.allowedKases) {
@@ -926,10 +934,11 @@ export async function readStream(cfg: DecryptConfiguration) {
     }
     allowList = new OriginAllowList(cfg.allowedKases);
   }
-  const { manifest, zipReader, centralDirectory } = await loadTDFStream(cfg.chunker);
+
   if (!manifest) {
     throw new InvalidFileError('Missing manifest data');
   }
+
   cfg.keyMiddleware ??= async (key) => key;
 
   const {

package/dist/cjs/src/tdf/PolicyObject.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUG9saWN5T2JqZWN0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3RkZi9Qb2xpY3lPYmplY3QudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist/cjs/src/tdf/TypedArray.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiVHlwZWRBcnJheS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy90ZGYvVHlwZWRBcnJheS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=