@opentdf/sdk 0.1.0-beta.1701

package/src/policy/granter.ts

@@ -0,0 +1,181 @@
+import { ConfigurationError } from '../errors.js';
+import { Attribute, AttributeRuleType, KeyAccessServer, Value } from './attributes.js';
+
+export type KeySplitStep = {
+  kas: KeyAccessServer;
+  sid?: string;
+};
+
+type AttributeClause = {
+  def: Attribute;
+  values: string[];
+};
+
+type AndClause = {
+  op: 'allOf';
+  kases: string[];
+};
+
+type HeirarchyClause = {
+  op: 'hierarchy';
+  kases: string[];
+};
+
+type OrClause = {
+  op: 'anyOf';
+  kases: string[];
+};
+
+type BooleanClause = AndClause | OrClause | HeirarchyClause;
+
+type BooleanOperator = BooleanClause['op'];
+
+type ComplexBooleanClause = {
+  op: BooleanOperator;
+  children: BooleanClause[];
+};
+
+export function booleanOperatorFor(rule?: AttributeRuleType): BooleanOperator {
+  if (!rule) {
+    return 'allOf';
+  }
+  switch (rule) {
+    case 'ATTRIBUTE_RULE_TYPE_ENUM_UNSPECIFIED':
+    case 'ATTRIBUTE_RULE_TYPE_ENUM_ALL_OF':
+      return 'allOf';
+    case 'ATTRIBUTE_RULE_TYPE_ENUM_ANY_OF':
+      return 'anyOf';
+    case 'ATTRIBUTE_RULE_TYPE_ENUM_HIERARCHY':
+      return 'hierarchy';
+  }
+}
+
+export function plan(dataAttrs: Value[]): KeySplitStep[] {
+  // KASes by value
+  const grants: Record<string, Set<string>> = {};
+  // KAS detail by KAS url
+  const kasInfo: Record<string, KeyAccessServer> = {};
+  // Attribute definitions in use
+  const prefixes: Set<string> = new Set();
+  // Values grouped by normalized attribute prefix
+  const allClauses: Record<string, AttributeClause> = {};
+  // Values by normalized FQN
+  const allValues: Record<string, Value> = {};
+
+  const addGrants = (val: string, gs?: KeyAccessServer[]): boolean => {
+    if (!gs?.length) {
+      if (!(val in grants)) {
+        grants[val] = new Set();
+      }
+      return false;
+    }
+    for (const g of gs) {
+      if (val in grants) {
+        grants[val].add(g.uri);
+      } else {
+        grants[val] = new Set([g.uri]);
+      }
+      kasInfo[g.uri] = g;
+    }
+    return true;
+  };
+
+  for (const v of dataAttrs) {
+    const { attribute, fqn } = v;
+    if (!attribute) {
+      throw new ConfigurationError(`attribute not defined for [${fqn}]`);
+    }
+    const valFqn = fqn.toLowerCase();
+    const attrFqn = attribute.fqn.toLowerCase();
+    if (!prefixes.has(attrFqn)) {
+      prefixes.add(attrFqn);
+      allClauses[attrFqn] = {
+        def: attribute,
+        values: [],
+      };
+    }
+    allClauses[attrFqn].values.push(valFqn);
+    allValues[valFqn] = v;
+    if (!addGrants(valFqn, v.grants)) {
+      if (!addGrants(valFqn, attribute.grants)) {
+        addGrants(valFqn, attribute.namespace?.grants);
+      }
+    }
+  }
+  const kcs: ComplexBooleanClause[] = [];
+  for (const attrClause of Object.values(allClauses)) {
+    const ccv: BooleanClause[] = [];
+    for (const term of attrClause.values) {
+      const grantsForTerm = Array.from(grants[term] || []);
+      if (grantsForTerm?.length) {
+        ccv.push({
+          op: 'anyOf',
+          kases: grantsForTerm,
+        });
+      }
+    }
+    const op = booleanOperatorFor(attrClause.def.rule);
+    kcs.push({
+      op,
+      children: ccv,
+    });
+  }
+  return simplify(kcs, kasInfo);
+}
+
+function simplify(
+  clauses: ComplexBooleanClause[],
+  kasInfo: Record<string, KeyAccessServer>
+): KeySplitStep[] {
+  const conjunction: Record<string, string[]> = {};
+  function keyFor(kases: string[]): string {
+    const k = Array.from(new Set([kases])).sort();
+    return k.join('|');
+  }
+  for (const { op, children } of clauses) {
+    if (!children) {
+      continue;
+    }
+    if (op === 'anyOf') {
+      const anyKids = [];
+      for (const bc of children) {
+        if (bc.op != 'anyOf') {
+          throw new Error('internal: autoconfigure inversion in disjunction');
+        }
+        if (!bc.kases?.length) {
+          continue;
+        }
+        anyKids.push(...bc.kases);
+      }
+      if (!anyKids?.length) {
+        continue;
+      }
+      const k = keyFor(anyKids);
+      conjunction[k] = anyKids;
+    } else {
+      for (const bc of children) {
+        if (bc.op != 'anyOf') {
+          throw new Error('insternal: autoconfigure inversion in conjunction');
+        }
+        if (!bc.kases?.length) {
+          continue;
+        }
+        const k = keyFor(bc.kases);
+        conjunction[k] = bc.kases;
+      }
+    }
+  }
+  const t: KeySplitStep[] = [];
+  let i = 0;
+  for (const k of Object.keys(conjunction).sort()) {
+    if (!conjunction[k]) {
+      continue;
+    }
+    i += 1;
+    const sid = '' + i;
+    for (const kas of conjunction[k]) {
+      t.push({ sid, kas: kasInfo[kas] });
+    }
+  }
+  return t;
+}

package/src/tdf/AttributeObject.ts

@@ -0,0 +1,27 @@
+import { type KasPublicKeyInfo } from '../access.js';
+
+export interface AttributeObject {
+  readonly attribute: string;
+  readonly isDefault?: boolean;
+  readonly displayName?: string;
+  /** PEM encoded public key */
+  readonly pubKey: string;
+  readonly kasUrl: string;
+  /** The most recent version 1.1.0. */
+  readonly schemaVersion?: string;
+}
+
+export async function createAttribute(
+  attribute: string,
+  pubKey: KasPublicKeyInfo,
+  kasUrl: string
+): Promise<AttributeObject> {
+  return {
+    attribute,
+    isDefault: false,
+    displayName: '',
+    pubKey: pubKey.publicKey,
+    kasUrl,
+    schemaVersion: '1.1.0',
+  };
+}

package/src/tdf/AttributeObjectJwt.ts

@@ -0,0 +1,3 @@
+export default interface AttributeObjectJwt {
+  readonly jwt: string;
+}

package/src/tdf/Crypto.ts

@@ -0,0 +1,42 @@
+export enum AlgorithmName {
+  ECDH = 'ECDH',
+  ECDSA = 'ECDSA',
+  ES256 = 'ES256',
+  HKDF = 'HKDF',
+  RSA_OAEP = 'RSA-OAEP',
+  RSA_PSS = 'RSA-PSS',
+}
+
+export enum NamedCurve {
+  P256 = 'P-256',
+  P384 = 'P-384',
+  P512 = 'P-512',
+}
+
+export enum CipherType {
+  AesGcm = 'AES-GCM',
+}
+
+export enum HashType {
+  Sha256 = 'SHA-256',
+}
+
+export enum KeyFormat {
+  Raw = 'raw',
+  Pkcs8 = 'pkcs8',
+  Spki = 'spki',
+}
+
+export enum KeyType {
+  Private = 'private',
+  Public = 'public',
+}
+
+export enum KeyUsageType {
+  Encrypt = 'encrypt',
+  Decrypt = 'decrypt',
+  Verify = 'verify',
+  Sign = 'sign',
+  UnwrapKey = 'unwrapKey',
+  WrapKey = 'wrapKey',
+}

package/src/tdf/EntityObject.ts

@@ -0,0 +1,18 @@
+import type AttributeObjectJwt from './AttributeObjectJwt.js';
+
+/**
+ * Defined by the TDF3 spec and generated by an Entity Attribute Service,
+ * this object (when accompanied by a valid cert) defines what attributes
+ * a client has access to.
+ */
+export interface EntityObject {
+  readonly aliases: string[];
+  readonly attributes: AttributeObjectJwt[];
+  /** This should be present on validated EOs only - it is written by an EAS */
+  readonly cert?: string;
+  readonly exp?: number;
+  readonly publicKey: string;
+  readonly userId: string;
+  /** The most recent version 1.1.0. */
+  readonly schemaVersion?: string;
+}

package/src/tdf/NanoTDF/NanoTDF.ts

@@ -0,0 +1,120 @@
+enum CipherType {
+  Aes256Gcm64, // Default cipher
+  Aes256Gcm96,
+  Aes256Gcm104,
+  Aes256Gcm112,
+  Aes256Gcm120,
+  Aes256Gcm128,
+}
+
+/**
+ * The Signature ECC Mode is used to determine the length of the signature at the end of a nanotdf. This, in
+ * combination with the previous HAS_SIGNATURE section, describe the signature of the nanotdf. The following table
+ * describes the valid values and the associated ECC Params.
+ */
+enum CurveName {
+  Secp256R1,
+  Secp384R1,
+  Secp521R1,
+}
+
+export enum ResourceLocatorProtocol {
+  Http,
+  Https,
+  Unreserverd,
+  SharedResourceDirectory = 0xff,
+}
+
+export enum PolicyType {
+  Remote,
+  EmbeddedText,
+  EmbeddedEncrypted, // Default policy
+  EmbeddedEncryptedPKA, // Todo: Not implemented
+}
+
+/**
+ * Resource Locator interface
+ */
+export interface ResourceLocator {
+  protocol: ResourceLocatorProtocol;
+  length: number;
+  body: string;
+}
+
+/**
+ * Policy interface
+ */
+export interface Policy {
+  type: PolicyType;
+  binding: Uint8Array;
+}
+
+/**
+ * Remote policy interface
+ */
+export interface RemotePolicy extends Policy {
+  protocol: ResourceLocatorProtocol;
+  urn: string;
+}
+
+/**
+ * Embedded policy interface
+ */
+export interface EmbeddedPolicy extends Policy {
+  content: Uint8Array;
+}
+
+/**
+ * Header interface
+ */
+export interface Header {
+  // Magic Number & Version
+  magicNumberVersion: Uint8Array;
+
+  // KAS Resource Locator
+  kas: ResourceLocator;
+
+  // ECC & Binding Mode
+  useECDSABinding: boolean;
+  ephemeralCurveName: CurveName;
+
+  // Symmetric & Payload Config
+  hasSignature: boolean;
+  signatureCurveName: CurveName;
+  symmetricCipher: CipherType;
+  // Auth tag length is not part of the spec, but is needed for decrypt
+  authTagLength: number;
+
+  // Policy
+  policy: RemotePolicy | EmbeddedPolicy;
+
+  // Ephemeral Public Key
+  ephemeralPublicKey: Uint8Array;
+}
+
+/**
+ * Payload interface
+ */
+export interface Payload {
+  iv: Uint8Array;
+  ciphertext: Uint8Array;
+  authTag: Uint8Array;
+  ciphertextAuthTag: Uint8Array;
+}
+
+/**
+ * Signature interface
+ */
+export interface Signature {
+  publicKey: Uint8Array;
+  signature: Uint8Array;
+}
+
+/**
+ * NanoTDF interface
+ */
+export interface NanoTDF {
+  header: Header;
+  payload: Payload;
+  signature: Signature;
+}

package/src/tdf/Policy.ts

@@ -0,0 +1,51 @@
+import { type AttributeObject } from './AttributeObject.js';
+import { v4 as uuid } from 'uuid';
+
+export default class Policy {
+  static CURRENT_VERSION = '1.1.0';
+
+  private uuidStr = uuid();
+  private dataAttributesList: AttributeObject[] = [];
+  private dissemList: string[] = [];
+  // private schemaVersionStr = Policy.CURRENT_VERSION;
+
+  /**
+   * Adds a group of entities, to the Policy's dissem list
+   *
+   * @param entities The entities will be added to the policy and
+   * they will have access to the TDF
+   */
+  addEntities(entities: string[]): void {
+    this.dissemList.push(...entities);
+
+    // Remove any duplicates
+    this.dissemList = this.dissemList.filter((elem, index, self) => {
+      return index === self.indexOf(elem);
+    });
+  }
+
+  /**
+   *
+   * Adds an Attribute object to the policy
+   *
+   * @param attribute will be added to the policy
+   */
+  addAttribute(attribute: AttributeObject): void {
+    this.dataAttributesList.push(attribute);
+  }
+
+  /**
+   * 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,
+      },
+    });
+  }
+}

package/src/tdf/PolicyObject.ts

@@ -0,0 +1,12 @@
+import { type AttributeObject } from './AttributeObject.js';
+
+export interface PolicyObjectBody {
+  readonly dataAttributes: AttributeObject[];
+  readonly dissem: string[];
+}
+
+export default interface PolicyObject {
+  readonly uuid: string;
+  readonly body: PolicyObjectBody;
+  readonly schemaVersion?: string;
+}

package/src/tdf/TypedArray.ts

@@ -0,0 +1,12 @@
+type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Uint8ClampedArray
+  | Float32Array
+  | Float64Array;
+
+export default TypedArray;

package/src/tdf/index.ts

@@ -0,0 +1,6 @@
+export { type AttributeObject, createAttribute } from './AttributeObject.js';
+export { type EntityObject } from './EntityObject.js';
+export { type default as PolicyObject } from './PolicyObject.js';
+export { type default as TypedArray } from './TypedArray.js';
+export { default as Policy } from './Policy.js';
+export * as Crypto from './Crypto.js';

package/src/types/index.ts

@@ -0,0 +1,55 @@
+import PolicyTypeEnum from '../nanotdf/enum/PolicyTypeEnum.js';
+
+export type InputSource =
+  | ReadableStream<Uint8Array>
+  | Uint8Array
+  | string
+  | ArrayBuffer
+  | Promise<ReadableStream<Uint8Array>>;
+
+type Header = {
+  magicNumberVersion: string[];
+  kas: {
+    protocol: number;
+    length: number;
+    body: string;
+  };
+  eccBindingMode: {
+    useECDSABinding: boolean;
+    ephemeralCurveName: number;
+  };
+  symmetricPayloadConfig: {
+    hasSignature: boolean;
+    signatureCurveName: number;
+    symmetricCipher: number;
+  };
+  ephemeralPublicKey: string[];
+};
+
+type HeaderPolicy = {
+  type: PolicyTypeEnum;
+  content: string[];
+  binding: string[];
+};
+
+type RemotePolicy = {
+  protocol: number;
+  length: number;
+  body: string;
+};
+
+export type PlainEmbeddedHeader = Header & {
+  policy: HeaderPolicy;
+};
+
+export type EmbeddedHeader = Header & {
+  policy: HeaderPolicy;
+};
+
+export type RemoteHeader = Header & {
+  policy: {
+    type: PolicyTypeEnum;
+    remotePolicy: RemotePolicy;
+    binding: string[];
+  };
+};

package/src/utils.ts

@@ -0,0 +1,149 @@
+import { type AxiosResponseHeaders, type RawAxiosResponseHeaders } from 'axios';
+import { exportSPKI, importX509 } from 'jose';
+
+import { base64 } from './encodings/index.js';
+import { pemCertToCrypto, pemPublicToCrypto } from './nanotdf-crypto/index.js';
+import { ConfigurationError } from './errors.js';
+
+/**
+ * Check to see if the given URL is 'secure'. This assumes:
+ *
+ * - `https` URLs are always secure
+ * - `http` URLS are allowed for localhost
+ * - And also for '`svc.cluster.local` and `.internal` URLs
+ *
+ * Note that this does not resolve the URL, so it is possible this could
+ * resolve to some other internal URL, and may return `false` on non-fully
+ * qualified internal URLs.
+ *
+ * @param url remote service to validate
+ * @returns the url is local or `https`
+ */
+export function validateSecureUrl(url: string): boolean {
+  const httpsRegex = /^https:/;
+  if (/^http:\/\/(localhost|127\.0\.0\.1)(:[0-9]{1,5})?($|\/)/.test(url)) {
+    console.warn(`Development URL detected: [${url}]`);
+  } else if (
+    /^http:\/\/([a-zA-Z.-]*[.])?svc\.cluster\.local($|\/)/.test(url) ||
+    /^http:\/\/([a-zA-Z.-]*[.])?internal(:[0-9]{1,5})?($|\/)/.test(url)
+  ) {
+    console.info(`Internal URL detected: [${url}]`);
+  } else if (!httpsRegex.test(url)) {
+    console.error(`Insecure KAS URL loaded. Are you running in a secure environment? [${url}]`);
+    return false;
+  }
+  return true;
+}
+
+export function padSlashToUrl(u: string): string {
+  if (u.endsWith('/')) {
+    return u;
+  }
+  return `${u}/`;
+}
+
+export function isBrowser() {
+  return typeof window !== 'undefined'; // eslint-disable-line
+}
+
+export const isFirefox = (): boolean => isBrowser() && 'InstallTrigger' in window;
+
+export const rstrip = (str: string, suffix = ' '): string => {
+  while (str && suffix && str.endsWith(suffix)) {
+    str = str.slice(0, -suffix.length);
+  }
+  return str;
+};
+
+/**
+ * Rough estimate of number of seconds to add to the current system clock time
+ * to get the clock time on the given server, or origin if not specified
+ * @param server a server to compute skew with
+ * @returns the number of seconds to add to the current local system clock time
+ * to get an rough guess of the time on the given server
+ */
+export const estimateSkew = async (serverEndpoint = window.origin): Promise<number> => {
+  const localUnixTimeBefore = Date.now();
+  const response = await fetch(serverEndpoint);
+  return estimateSkewFromHeaders(response.headers, localUnixTimeBefore);
+};
+
+export type AnyHeaders = AxiosResponseHeaders | RawAxiosResponseHeaders | Headers;
+
+/**
+ * Rough estimate of number of seconds to add to the curren time to get
+ * the clock time on the server that responded with the headers object.
+ * @param headers A set of headers, which must include the `date` header
+ * @param dateNowBefore time before initiating the request, usually by calling
+ * `Date.now()`. Note this is in milliseconds since the epoch, while the
+ * estimate is given in seconds.
+ * @returns the number of seconds to add to the current local system clock time
+ * to get an rough guess of the time on the server that was used
+ */
+export const estimateSkewFromHeaders = (headers: AnyHeaders, dateNowBefore?: number): number => {
+  const localUnixTimeBefore = (dateNowBefore || Date.now()) / 1000;
+  let serverDateString;
+  if (headers.get) {
+    serverDateString = (headers as Headers).get('Date');
+  } else {
+    serverDateString = (headers as AxiosResponseHeaders | RawAxiosResponseHeaders).date;
+  }
+  if (serverDateString === null) {
+    throw Error('Cannot get access to Date header!');
+  }
+  const serverUnixTime = Date.parse(serverDateString) / 1000;
+  const localUnixTimeAfter = Date.now() / 1000;
+  const deltaBefore = serverUnixTime - localUnixTimeBefore;
+  const deltaAfter = serverUnixTime - localUnixTimeAfter;
+
+  return Math.round((deltaBefore + deltaAfter) / 2);
+};
+
+export function addNewLines(str: string): string {
+  if (!str) {
+    return str;
+  }
+  let inputString = str;
+  let finalString = '';
+  while (inputString.length > 0) {
+    finalString += inputString.substring(0, 64) + '\r\n';
+    inputString = inputString.substring(64);
+  }
+  return finalString;
+}
+
+export async function cryptoPublicToPem(publicKey: CryptoKey): Promise<string> {
+  if (publicKey.type !== 'public') {
+    throw new ConfigurationError('incorrect key type');
+  }
+
+  const exportedPublicKey = await crypto.subtle.exportKey('spki', publicKey);
+  const b64 = base64.encodeArrayBuffer(exportedPublicKey);
+  const pem = addNewLines(b64);
+  return `-----BEGIN PUBLIC KEY-----\r\n${pem}-----END PUBLIC KEY-----`;
+}
+
+export async function pemToCryptoPublicKey(pem: string): Promise<CryptoKey> {
+  if (/-----BEGIN PUBLIC KEY-----/.test(pem)) {
+    return pemPublicToCrypto(pem);
+  } else if (/-----BEGIN CERTIFICATE-----/.test(pem)) {
+    return pemCertToCrypto(pem);
+  }
+  // This can happen in several circumstances:
+  // - When parsing a PEM key from a KAS server
+  // - When converting between PEM and CryptoKey formats for user provided session keys (e.g. for DPoP)
+  throw new TypeError(`unsupported pem type [${pem}]`);
+}
+
+export async function extractPemFromKeyString(keyString: string): Promise<string> {
+  let pem: string = keyString;
+
+  // Skip the public key extraction if we find that the KAS url provides a
+  // PEM-encoded key instead of certificate
+  if (keyString.includes('CERTIFICATE')) {
+    const cert = await importX509(keyString, 'RS256', { extractable: true });
+    pem = await exportSPKI(cert);
+  }
+
+  return pem;
+}

package/src/version.ts

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