@opentdf/sdk 0.1.0-beta.1701

package/tdf3/src/models/attribute-set.ts

@@ -0,0 +1,142 @@
+import { decodeJwt } from 'jose';
+
+export type AttributeObject = {
+  attribute: string;
+  kasUrl?: string;
+  kid?: string;
+  pubKey?: string;
+  displayName?: string;
+  isDefault?: boolean;
+  jwt?: string;
+};
+
+export class AttributeSet {
+  attributes: AttributeObject[];
+
+  verbose: boolean = false;
+
+  defaultAttribute?: AttributeObject;
+
+  constructor() {
+    this.attributes = [];
+  }
+
+  /**
+   * Check if attribute is in the list
+   * @param attribute URL of the attribute
+   * @return if attribute is in the set
+   */
+  has(attribute = ''): boolean {
+    // This could be much more elegant with something other than an
+    // array as the data structure. This is OK-ish only because the
+    // expected size of the data structure is small
+    // console.log(">>> ----- Has Attribute" + attribute);
+    return !!this.attributes.find((attrObj) => attrObj.attribute === attribute);
+  }
+
+  /**
+   * Get an attribute by URL
+   * @param  attribute URL of the attribute
+   * @return attribute in object form, if found
+   */
+  get(attribute = ''): AttributeObject | null {
+    // This could be much more elegant with something other than an
+    // array as the data structure. This is OK-ish only because the
+    // expected size of the data structure is small
+    // console.log(">>> ----- Get Attribute" + attribute);
+    const result = this.attributes.filter((attrObj) => attrObj.attribute == attribute);
+    return result.length > 0 ? result[0] : null;
+  }
+
+  /**
+   * Get all the attributes.
+   * @return default attribute in object form or null
+   */
+  getDefault(): AttributeObject | null {
+    return this.defaultAttribute || null;
+  }
+
+  /**
+   * Get the default attribute, if it exists.
+   * @return return all the attribute urls
+   */
+  getUrls(): string[] {
+    return this.attributes.map((attr) => attr.attribute);
+  }
+
+  /**
+   * Add an attribute to the set. Should be idempotent.
+   * @param attrObj AttributeObject to add, in non-JWT form
+   * @return the attribute object if successful, or null
+   */
+  addAttribute(attrObj: AttributeObject): AttributeObject | null {
+    // Check for duplicate entries to assure idempotency.
+    if (this.has(attrObj.attribute)) {
+      // This may be a common occurance, so only un-comment this log message
+      // if you want verbose mode.
+      // console.log(`Attribute ${attrObj.attribute} is already loaded.`);
+      return null; // reject silently
+    }
+
+    if (attrObj.isDefault === true) {
+      if (this.defaultAttribute && this.defaultAttribute.attribute !== attrObj.attribute) {
+        // Remove the existing default attribute to make room for the new one
+        this.deleteAttribute(this.defaultAttribute.attribute);
+      }
+      this.defaultAttribute = attrObj;
+    }
+    this.attributes.push(attrObj);
+    return attrObj;
+  }
+
+  /**
+   * Delete an attribute from the set. Should be idempotent.
+   * @param attrUrl - URL of Attribute object to delete.
+   * @return The attribute object if successful or null if not
+   */
+  deleteAttribute(attrUrl = ''): AttributeObject | null {
+    const deleted = this.get(attrUrl);
+    if (deleted) {
+      this.attributes = this.attributes.filter((attrObj) => attrObj.attribute != attrUrl);
+    }
+    return deleted;
+  }
+
+  /**
+   * Add a list of attributes in object form
+   * @param  attributes List of attribute objects as provided in an EntityObject
+   * @param  easPublicKey EAS public key for decrypting the JWTs
+   * @return list of attribute objects
+   */
+  addAttributes(attributes: AttributeObject[] = []): (AttributeObject | null)[] {
+    return attributes
+      .map((attrObj) => {
+        return this.addAttribute(attrObj); // Returns promise
+      })
+      .filter((x) => x);
+  }
+
+  /**
+   * Add an attribute in JWT form = { jwt: <string jwt> }
+   * @param  {Object} jwtAttribute - Attribute object in JWT form.
+   * @return {Object} - Decrypted and added attribute object
+   */
+  addJwtAttribute(jwtAttribute: { jwt: string }) {
+    const attrJwt = jwtAttribute?.jwt;
+    // Can't verify the JWT because the client does not have the easPublicKey,
+    // but the contents of the JWT can be decoded.
+    const attrObjPayload = attrJwt && decodeJwt(attrJwt);
+    if (!attrObjPayload) {
+      return null;
+    }
+    // JWT payloads contain many things, incluing .iat and .exp. This
+    // extraneous material should be stripped away before adding the
+    // attribute to the attributeSet.
+    const { attribute, displayName, pubKey, kasUrl } = attrObjPayload as AttributeObject;
+    const attrObj: AttributeObject = { attribute, displayName, pubKey, kasUrl, jwt: attrJwt };
+    if (attrObjPayload.isDefault) {
+      attrObj.isDefault = !!attrObjPayload.isDefault;
+    }
+    return this.addAttribute(attrObj);
+  }
+}

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

@@ -0,0 +1,172 @@
+import { keySplit } from '../utils/index.js';
+import { base64, hex } from '../../../src/encodings/index.js';
+import { Binary } from '../binary.js';
+import { type SymmetricCipher } from '../ciphers/symmetric-cipher-base.js';
+import { type KeyAccess, type KeyAccessObject } from './key-access.js';
+import { type Policy } from './policy.js';
+import {
+  type CryptoService,
+  type DecryptResult,
+  type EncryptResult,
+} from '../crypto/declarations.js';
+import { IntegrityAlgorithm } from '../tdf.js';
+import { ConfigurationError } from '../../../src/errors.js';
+
+export type KeyInfo = {
+  readonly unwrappedKeyBinary: Binary;
+  readonly unwrappedKeyIvBinary: Binary;
+};
+
+export type Segment = {
+  readonly hash: string;
+  // If not present, segmentSizeDefault must be defined and used.
+  readonly segmentSize?: number;
+  // If not present, encryptedSegmentSizeDefault must be defined and used.??
+  readonly encryptedSegmentSize?: number;
+};
+
+export type SplitType = 'split';
+
+export type EncryptionInformation = {
+  readonly type: SplitType;
+  readonly keyAccess: KeyAccessObject[];
+  readonly integrityInformation: {
+    readonly rootSignature: {
+      alg: IntegrityAlgorithm;
+      sig: string;
+    };
+    segmentHashAlg?: IntegrityAlgorithm;
+    segments: Segment[];
+    segmentSizeDefault?: number;
+    encryptedSegmentSizeDefault?: number;
+  };
+  readonly method: {
+    readonly algorithm: string;
+    isStreamable: boolean;
+    readonly iv: string;
+  };
+  policy: string;
+};
+
+export class SplitKey {
+  readonly cryptoService: CryptoService;
+  keyAccess: KeyAccess[];
+
+  constructor(public readonly cipher: SymmetricCipher) {
+    this.cryptoService = cipher.cryptoService;
+    this.keyAccess = [];
+  }
+
+  async generateKey(): Promise<KeyInfo> {
+    const unwrappedKey = await this.cipher.generateKey();
+    const unwrappedKeyBinary = Binary.fromString(hex.decode(unwrappedKey));
+    const unwrappedKeyIvBinary = await this.generateIvBinary();
+    return { unwrappedKeyBinary, unwrappedKeyIvBinary };
+  }
+
+  async encrypt(
+    contentBinary: Binary,
+    keyBinary: Binary,
+    ivBinaryOptional?: Binary
+  ): Promise<EncryptResult> {
+    const ivBinary = ivBinaryOptional || (await this.generateIvBinary());
+    return this.cipher.encrypt(contentBinary, keyBinary, ivBinary);
+  }
+
+  async decrypt(content: Uint8Array, keyBinary: Binary): Promise<DecryptResult> {
+    return this.cipher.decrypt(content, keyBinary);
+  }
+
+  async getKeyAccessObjects(policy: Policy, keyInfo: KeyInfo): Promise<KeyAccessObject[]> {
+    const splitIds = [...new Set(this.keyAccess.map(({ sid }) => sid))].sort((a, b) =>
+      a.localeCompare(b)
+    );
+    const unwrappedKeySplitBuffers = await keySplit(
+      new Uint8Array(keyInfo.unwrappedKeyBinary.asByteArray()),
+      splitIds.length,
+      this.cryptoService
+    );
+    const splitsByName = Object.fromEntries(
+      splitIds.map((sid, index) => [sid, unwrappedKeySplitBuffers[index]])
+    );
+
+    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 unwrappedKeySplitBinary = Binary.fromArrayBuffer(unwrappedKeySplitBuffer.buffer);
+
+      const metadata = item.metadata || '';
+      const metadataStr = (
+        typeof metadata === 'object'
+          ? JSON.stringify(metadata)
+          : typeof metadata === 'string'
+            ? metadata
+            : () => {
+                throw new ConfigurationError(
+                  "KAO generation failure: metadata isn't a string or object"
+                );
+              }
+      ) as string;
+
+      const metadataBinary = Binary.fromArrayBuffer(new TextEncoder().encode(metadataStr));
+
+      const encryptedMetadataResult = await this.encrypt(
+        metadataBinary,
+        unwrappedKeySplitBinary,
+        keyInfo.unwrappedKeyIvBinary
+      );
+
+      const encryptedMetadataOb = {
+        ciphertext: base64.encode(encryptedMetadataResult.payload.asString()),
+        iv: base64.encode(keyInfo.unwrappedKeyIvBinary.asString()),
+      };
+
+      const encryptedMetadataStr = JSON.stringify(encryptedMetadataOb);
+      const keyAccessObject = await item.write(
+        policy,
+        unwrappedKeySplitBuffer,
+        encryptedMetadataStr
+      );
+      keyAccessObjects.push(keyAccessObject);
+    }
+
+    return keyAccessObjects;
+  }
+
+  async generateIvBinary(): Promise<Binary> {
+    const iv = await this.cipher.generateInitializationVector();
+    return Binary.fromString(hex.decode(iv));
+  }
+
+  async write(policy: Policy, keyInfo: KeyInfo): Promise<EncryptionInformation> {
+    const algorithm = this.cipher?.name;
+    if (!algorithm) {
+      // Hard coded as part of the cipher object. This should not be reachable.
+      throw new ConfigurationError('uninitialized cipher type');
+    }
+    const keyAccessObjects = await this.getKeyAccessObjects(policy, keyInfo);
+
+    // For now we're only concerned with a single (first) key access object
+    const policyForManifest = base64.encode(JSON.stringify(policy));
+
+    return {
+      type: 'split',
+      keyAccess: keyAccessObjects,
+      method: {
+        algorithm,
+        isStreamable: false,
+        iv: base64.encode(keyInfo.unwrappedKeyIvBinary.asString()),
+      },
+      integrityInformation: {
+        rootSignature: {
+          alg: 'HS256',
+          sig: '',
+        },
+        segmentHashAlg: 'GMAC',
+        segments: [],
+      },
+      policy: policyForManifest,
+    };
+  }
+}

package/tdf3/src/models/index.ts

@@ -0,0 +1,8 @@
+export * from './attribute-set.js';
+export * from './encryption-information.js';
+export * from './key-access.js';
+export * from './manifest.js';
+export * from './payload.js';
+export * from './policy.js';
+export * from './upsert-response.js';
+export * from '../assertions.js';

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

@@ -0,0 +1,128 @@
+import { Binary } from '../binary.js';
+import { base64, hex } from '../../../src/encodings/index.js';
+import * as cryptoService from '../crypto/index.js';
+import { Policy } from './policy.js';
+
+export type KeyAccessType = 'remote' | 'wrapped';
+
+export function isRemote(keyAccessJSON: KeyAccess | KeyAccessObject): boolean {
+  return keyAccessJSON.type === 'remote';
+}
+
+export class Wrapped {
+  readonly type = 'wrapped';
+  keyAccessObject?: KeyAccessObject;
+
+  constructor(
+    public readonly url: string,
+    public readonly kid: string | undefined,
+    public readonly publicKey: string,
+    public readonly metadata: unknown,
+    public readonly sid: string
+  ) {}
+
+  async write(
+    policy: Policy,
+    keyBuffer: 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 policyBinding = await cryptoService.hmac(
+      hex.encodeArrayBuffer(keyBuffer),
+      base64.encode(policyStr)
+    );
+
+    this.keyAccessObject = {
+      type: 'wrapped',
+      url: this.url,
+      protocol: 'kas',
+      wrappedKey: base64.encode(wrappedKeyBinary.asString()),
+      encryptedMetadata: base64.encode(encryptedMetadataStr),
+      policyBinding: {
+        alg: 'HS256',
+        hash: base64.encode(policyBinding),
+      },
+    };
+    if (this.kid) {
+      this.keyAccessObject.kid = this.kid;
+    }
+    if (this.sid?.length) {
+      this.keyAccessObject.sid = this.sid;
+    }
+
+    return this.keyAccessObject;
+  }
+}
+
+export class Remote {
+  readonly type = 'remote';
+  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
+  ) {}
+
+  async write(
+    policy: Policy,
+    keyBuffer: Uint8Array,
+    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());
+
+    this.keyAccessObject = {
+      type: 'remote',
+      url: this.url,
+      protocol: 'kas',
+      wrappedKey: this.wrappedKey,
+      encryptedMetadata: base64.encode(encryptedMetadataStr),
+      policyBinding: {
+        alg: 'HS256',
+        hash: base64.encode(policyBinding),
+      },
+    };
+    if (this.kid) {
+      this.keyAccessObject.kid = this.kid;
+    }
+    return this.keyAccessObject;
+  }
+}
+
+export type KeyAccess = Remote | Wrapped;
+
+export type KeyAccessObject = {
+  sid?: string;
+  type: KeyAccessType;
+  url: string;
+  kid?: string;
+  protocol: 'kas';
+  wrappedKey?: string;
+  policyBinding?: {
+    alg: string;
+    hash: string;
+  };
+  encryptedMetadata?: string;
+};

package/tdf3/src/models/manifest.ts

@@ -0,0 +1,9 @@
+import { type Assertion } from '../assertions.js';
+import { type Payload } from './payload.js';
+import { type EncryptionInformation } from './encryption-information.js';
+
+export type Manifest = {
+  payload: Payload;
+  encryptionInformation: EncryptionInformation;
+  assertions: Assertion[];
+};

package/tdf3/src/models/payload.ts

@@ -0,0 +1,6 @@
+export type Payload = {
+  type: string; // "reference";
+  url: string; // "0.payload"
+  protocol: string; // "zip"
+  isEncrypted: boolean; // true
+};

package/tdf3/src/models/policy.ts

@@ -0,0 +1,35 @@
+import { ConfigurationError } from '../../../src/errors.js';
+import { AttributeObject } from './attribute-set.js';
+
+export const CURRENT_VERSION = '1.1.0';
+
+export type PolicyBody = {
+  dataAttributes: AttributeObject[];
+  dissem: string[];
+};
+
+export type Policy = {
+  tdf_spec_version?: string;
+  uuid?: string;
+  body?: PolicyBody;
+};
+
+export function validatePolicyObject(policyMaybe: unknown): policyMaybe is Policy {
+  if (typeof policyMaybe !== 'object') {
+    throw new ConfigurationError(
+      `The given policy reference must be an object, not: ${policyMaybe}`
+    );
+  }
+  const policy = policyMaybe as Policy;
+  const missingFields = [];
+  if (!policy.uuid) missingFields.push('uuid');
+  if (!policy.body) missingFields.push('body', 'body.dissem');
+  if (policy.body && !policy.body.dissem) missingFields.push('body.dissem');
+
+  if (missingFields.length) {
+    throw new ConfigurationError(
+      `The given policy object requires the following properties: ${missingFields}`
+    );
+  }
+  return true;
+}

package/tdf3/src/models/upsert-response.ts

@@ -0,0 +1,17 @@
+export type ArtifactFinder = {
+  upload?: string;
+  // Download URL for the payload. This can be a direct link to the file (S3), or a proxy URL.
+  download: string;
+  key?: string;
+  bucket?: string;
+};
+
+export type UpsertResponse = {
+  uuid: string;
+  storageLinks: {
+    payload: ArtifactFinder & {
+      proxy?: boolean | string;
+    };
+    metadata?: ArtifactFinder;
+  };
+}[][];