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

package/src/policy/granter.ts

@@ -1,9 +1,13 @@
 import { ConfigurationError } from '../errors.js';
 import { Attribute, AttributeRuleType, KeyAccessServer, Value } from './attributes.js';
+import { SimpleKasPublicKey } from '../platform/policy/objects_pb.js';
 
-export type KeySplitStep = {
-  kas: KeyAccessServer;
-  sid?: string;
+type KeyHolder = KeyAccessServer | (SimpleKasPublicKey & { kasUri: string });
+
+type KeySplitStep = {
+  kas: KeyHolder;
+  kid?: string;
+  sid: string;
 };
 
 type AttributeClause = {
@@ -13,17 +17,17 @@ type AttributeClause = {
 
 type AndClause = {
   op: 'allOf';
-  kases: string[];
+  granters: KeyHolder[];
 };
 
 type HeirarchyClause = {
   op: 'hierarchy';
-  kases: string[];
+  granters: KeyHolder[];
 };
 
 type OrClause = {
   op: 'anyOf';
-  kases: string[];
+  granters: KeyHolder[];
 };
 
 type BooleanClause = AndClause | OrClause | HeirarchyClause;
@@ -49,53 +53,51 @@ export function booleanOperatorFor(rule?: AttributeRuleType): BooleanOperator {
   }
 }
 
+type ValueFQN = string;
 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();
+  const granters: Record<ValueFQN, Set<KeyHolder>> = Object.create(null);
   // Values grouped by normalized attribute prefix
-  const allClauses: Record<string, AttributeClause> = {};
-  // Values by normalized FQN
-  const allValues: Record<string, Value> = {};
+  const allClauses: Record<string, AttributeClause> = Object.create(null);
 
-  const addGrants = (val: string, gs?: KeyAccessServer[]): boolean => {
+  const addGrants = (valueFQN: string, gs?: KeyHolder[]): boolean => {
+    if (!(valueFQN in granters)) {
+      granters[valueFQN] = new Set();
+    }
     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;
+      granters[valueFQN].add(g);
     }
     return true;
   };
 
   for (const v of dataAttrs) {
-    const { attribute, fqn } = v;
+    const { attribute, fqn, kasKeys } = 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);
+    if (!(attrFqn in allClauses)) {
       allClauses[attrFqn] = {
         def: attribute,
         values: [],
       };
     }
     allClauses[attrFqn].values.push(valFqn);
-    allValues[valFqn] = v;
-    if (!addGrants(valFqn, v.grants)) {
+    const validKasKeys = kasKeys
+      .map((kasKey) => {
+        if (!kasKey.publicKey) {
+          return null;
+        }
+        return Object.assign({ kasUri: kasKey.kasUri }, kasKey.publicKey);
+      })
+      .filter((kasKey) => kasKey !== null);
+    if (validKasKeys.length) {
+      addGrants(valFqn, validKasKeys);
+    } else if (!addGrants(valFqn, v.grants)) {
       if (!addGrants(valFqn, attribute.grants)) {
         addGrants(valFqn, attribute.namespace?.grants);
       }
@@ -103,64 +105,80 @@ export function plan(dataAttrs: Value[]): KeySplitStep[] {
   }
   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({
+    // Create wrapper clauses for each value, [(ANY_OF Value-1), (ANY_OF Value-2)]
+    const individualValueClauses: BooleanClause[] = [];
+    for (const attrValue of attrClause.values) {
+      const grantersForAttr = granters[attrValue] || new Set();
+      if (grantersForAttr.size) {
+        individualValueClauses.push({
           op: 'anyOf',
-          kases: grantsForTerm,
+          granters: Array.from(grantersForAttr.values()),
         });
       }
     }
+    // Use proper boolean operation with wrapped values.
     const op = booleanOperatorFor(attrClause.def?.rule);
     kcs.push({
       op,
-      children: ccv,
+      children: individualValueClauses,
     });
   }
-  return simplify(kcs, kasInfo);
+  return simplify(kcs);
 }
 
-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('|');
+function simplify(clauses: ComplexBooleanClause[]): KeySplitStep[] {
+  const conjunction: Record<string, KeyHolder[]> = {};
+  function keyFor(granters: KeyHolder[]): string {
+    const keyParts = granters
+      .map((keyHolder) => {
+        const keyParts: string[] = [];
+        if ('kid' in keyHolder) {
+          keyParts.push(keyHolder.kasUri);
+          keyParts.push(keyHolder.kid);
+        } else {
+          keyParts.push(keyHolder.uri);
+          keyParts.push('');
+        }
+        return [keyHolder, keyParts.join('/')] as [KeyHolder, string];
+      })
+      .sort(([, sortKeyA], [, sortKeyB]) => {
+        return sortKeyA.localeCompare(sortKeyB);
+      })
+      .map(([, sortKey]) => {
+        return sortKey;
+      });
+    return keyParts.join(':');
   }
   for (const { op, children } of clauses) {
     if (!children) {
       continue;
     }
     if (op === 'anyOf') {
-      const anyKids = [];
+      const granters: KeyHolder[] = [];
       for (const bc of children) {
         if (bc.op != 'anyOf') {
           throw new Error('internal: autoconfigure inversion in disjunction');
         }
-        if (!bc.kases?.length) {
+        if (!bc.granters.length) {
           continue;
         }
-        anyKids.push(...bc.kases);
+        granters.push(...bc.granters);
       }
-      if (!anyKids?.length) {
+      if (!granters.length) {
         continue;
       }
-      const k = keyFor(anyKids);
-      conjunction[k] = anyKids;
+      const k = keyFor(granters);
+      conjunction[k] = granters;
     } else {
       for (const bc of children) {
         if (bc.op != 'anyOf') {
-          throw new Error('insternal: autoconfigure inversion in conjunction');
+          throw new Error('internal: autoconfigure inversion in conjunction');
         }
-        if (!bc.kases?.length) {
+        if (!bc.granters.length) {
           continue;
         }
-        const k = keyFor(bc.kases);
-        conjunction[k] = bc.kases;
+        const k = keyFor(bc.granters);
+        conjunction[k] = bc.granters;
       }
     }
   }
@@ -173,7 +191,15 @@ function simplify(
     i += 1;
     const sid = '' + i;
     for (const kas of conjunction[k]) {
-      t.push({ sid, kas: kasInfo[kas] });
+      if ('kid' in kas) {
+        t.push({ sid, kas: kas, kid: kas.kid });
+      } else if (kas.publicKey && kas.publicKey.publicKey.case === 'cached') {
+        kas.publicKey.publicKey.value.keys.forEach((key) => {
+          t.push({ sid, kas: kas, kid: key.kid });
+        });
+      } else {
+        t.push({ sid, kas: kas });
+      }
     }
   }
   return t;

package/src/seekable.ts

@@ -33,12 +33,30 @@ export const fromBrowserFile = (fileRef: Blob): Chunker => {
   };
 };
 
+/**
+ * Creates a seekable object from a buffer.
+ * @param source A Uint8Array to read from.
+ * If byteStart and byteEnd are not provided, reads the entire array.
+ * If byteStart is provided, reads from that index to the end of the array.
+ * If byteEnd is provided, reads from byteStart to byteEnd (exclusive).
+ * If both byteStart and byteEnd are provided, reads from byteStart to byteEnd (exclusive).
+ * @returns A promise that resolves to a Uint8Array containing the requested data.
+ */
 export const fromBuffer = (source: Uint8Array): Chunker => {
   return (byteStart?: number, byteEnd?: number) => {
     return Promise.resolve(source.slice(byteStart, byteEnd));
   };
 };
 
+/**
+ * Creates a seekable object from a string.
+ * @param source A string to read from.
+ * If byteStart and byteEnd are not provided, reads the entire string.
+ * If byteStart is provided, reads from that index to the end of the string.
+ * If byteEnd is provided, reads from byteStart to byteEnd (exclusive).
+ * If both byteStart and byteEnd are provided, reads from byteStart to byteEnd (exclusive).
+ * @returns A promise that resolves to a Uint8Array containing the requested data.
+ */
 export const fromString = (source: string): Chunker => {
   return fromBuffer(new TextEncoder().encode(source));
 };
@@ -110,6 +128,12 @@ export const fromUrl = async (location: string): Promise<Chunker> => {
   };
 };
 
+/**
+ * Creates a seekable object from a source.
+ * @param source A Source object containing the type and location of the data.
+ * @returns A promise that resolves to a Chunker function.
+ * @throws ConfigurationError if the source type is not supported or the location is invalid.
+ */
 export const fromSource = async ({ type, location }: Source): Promise<Chunker> => {
   switch (type) {
     case 'buffer':
@@ -139,6 +163,13 @@ export const fromSource = async ({ type, location }: Source): Promise<Chunker> =
   }
 };
 
+/**
+ * Converts a Source object to a ReadableStream.
+ * @param source A Source object containing the type and location of the data.
+ * Converts the source to a ReadableStream of Uint8Array.
+ * This is useful for streaming data from various sources like files, remote URLs, or chunkers.
+ * @returns A ReadableStream of Uint8Array.
+ */
 export async function sourceToStream(source: Source): Promise<ReadableStream<Uint8Array>> {
   switch (source.type) {
     case 'stream':

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:
  *
@@ -35,6 +38,12 @@ export function validateSecureUrl(url: string): boolean {
   return true;
 }
 
+/**
+ * Pads a URL with a trailing slash if it does not already have one.
+ * This is useful for ensuring that URLs are in a consistent format.
+ * @param u The URL to pad.
+ * @returns The padded URL.
+ */
 export function padSlashToUrl(u: string): string {
   if (u.endsWith('/')) {
     return u;
@@ -42,10 +51,21 @@ export function padSlashToUrl(u: string): string {
   return `${u}/`;
 }
 
+/**
+ * Checks if the current environment is a browser.
+ * This is useful for determining if certain APIs or features are available.
+ * @returns true if running in a browser, false otherwise.
+ */
 export function isBrowser() {
   return typeof window !== 'undefined'; // eslint-disable-line
 }
 
+/**
+ * Removes trailing characters from a string.
+ * @param str The string to trim.
+ * @param suffix The suffix to remove (default is a single space).
+ * @returns The trimmed string.
+ */
 export const rstrip = (str: string, suffix = ' '): string => {
   while (str && suffix && str.endsWith(suffix)) {
     str = str.slice(0, -suffix.length);
@@ -92,6 +112,15 @@ export const estimateSkewFromHeaders = (headers: AnyHeaders, dateNowBefore?: num
   return Math.round((deltaBefore + deltaAfter) / 2);
 };
 
+/**
+ * Adds new lines to a string every 64 characters.
+ * @param str A string to add new lines to.
+ * This function takes a string and adds new lines every 64 characters.
+ * If the string is empty or undefined, it returns the original string.
+ * This is useful for formatting long strings, such as public keys or certificates,
+ * to ensure they are properly formatted for PEM encoding.
+ * @returns The formatted string with new lines added.
+ */
 export function addNewLines(str: string): string {
   if (!str) {
     return str;
@@ -105,6 +134,11 @@ export function addNewLines(str: string): string {
   return finalString;
 }
 
+/**
+ * Creates a PEM-encoded string from a public key.
+ * @param publicKey The public key to convert.
+ * @returns A promise that resolves to a PEM-encoded string.
+ */
 export async function cryptoPublicToPem(publicKey: CryptoKey): Promise<string> {
   if (publicKey.type !== 'public') {
     throw new ConfigurationError('incorrect key type');
@@ -116,6 +150,11 @@ export async function cryptoPublicToPem(publicKey: CryptoKey): Promise<string> {
   return `-----BEGIN PUBLIC KEY-----\r\n${pem}-----END PUBLIC KEY-----`;
 }
 
+/**
+ * Converts a PEM-encoded public key to a CryptoKey.
+ * @param pem The PEM-encoded public key.
+ * @returns A promise that resolves to a CryptoKey.
+ */
 export async function pemToCryptoPublicKey(pem: string): Promise<CryptoKey> {
   if (/-----BEGIN PUBLIC KEY-----/.test(pem)) {
     return pemPublicToCrypto(pem);
@@ -128,6 +167,15 @@ export async function pemToCryptoPublicKey(pem: string): Promise<CryptoKey> {
   throw new TypeError(`unsupported pem type [${pem}]`);
 }
 
+/**
+ * Extracts the PEM-encoded public key from a key string.
+ * @param keyString A string containing a public key or certificate.
+ * This function extracts the PEM-encoded public key from a given key string.
+ * If the key string contains a certificate, it imports the certificate and exports
+ * the public key in PEM format. If the key string is already in PEM format, it returns
+ * the key string as is.
+ * @returns A promise that resolves to a PEM-encoded public key.
+ */
 export async function extractPemFromKeyString(keyString: string): Promise<string> {
   let pem: string = keyString;
 
@@ -143,6 +191,12 @@ export async function extractPemFromKeyString(keyString: string): Promise<string
 
 /**
  * Extracts the error message from an RPC catch error.
+ * @param error An error object, typically from a network request.
+ * This function extracts the error message from a ConnectError or a generic Error.
+ * If the error is a ConnectError or a standard Error, it returns the message.
+ * If the error is of an unknown type, it returns a default message indicating
+ * that an unknown network error occurred.
+ * @returns The extracted error message.
  */
 export function extractRpcErrorMessage(error: unknown): string {
   if (error instanceof ConnectError || error instanceof Error) {
@@ -153,8 +207,11 @@ export function extractRpcErrorMessage(error: unknown): string {
 
 /**
  * Converts a KAS endpoint URL to a platform URL.
- * If the KAS endpoint ends with '/kas', it returns the host url
- * Otherwise, it returns the original KAS endpoint.
+ * @param endpoint The KAS endpoint URL to extract the platform URL from.
+ * This function extracts the base URL from a KAS endpoint URL.
+ * It removes any trailing slashes and specific path segments related to rewrap or kas.
+ * This is useful for obtaining the base URL for further API requests.
+ * @returns The base URL of the platform.
  */
 export function getPlatformUrlFromKasEndpoint(endpoint: string): string {
   let result = endpoint || '';
@@ -169,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/assertions.ts

@@ -2,6 +2,7 @@ import { canonicalizeEx } from 'json-canonicalize';
 import { SignJWT, jwtVerify } from 'jose';
 import { base64, hex } from '../../src/encodings/index.js';
 import { ConfigurationError, IntegrityError, InvalidFileError } from '../../src/errors.js';
+import { tdfSpecVersion, version as sdkVersion } from '../../src/version.js';
 
 export type AssertionKeyAlg = 'ES256' | 'RS256' | 'HS256';
 export type AssertionType = 'handling' | 'other';
@@ -43,7 +44,9 @@ export type AssertionPayload = {
  * @returns the hexadecimal string representation of the hash
  */
 export async function hash(a: Assertion): Promise<string> {
-  const result = canonicalizeEx(a, { exclude: ['binding', 'hash', 'sign', 'verify'] });
+  const result = canonicalizeEx(a, {
+    exclude: ['binding', 'hash', 'sign', 'verify', 'signingKey'],
+  });
 
   const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(result));
   return hex.encodeArrayBuffer(hash);
@@ -227,6 +230,54 @@ export type AssertionVerificationKeys = {
   Keys: Record<string, AssertionKey>;
 };
 
+/**
+ * Metadata structure for system information.
+ */
+type SystemMetadata = {
+  tdf_spec_version: string;
+  creation_date: string;
+  sdk_version: string;
+  browser_user_agent?: string;
+  // platform is often the same as os in browser, but kept for consistency with original Go struct
+  platform?: string;
+};
+
+/**
+ * Returns a default assertion configuration populated with system metadata.
+ */
+export function getSystemMetadataAssertionConfig(): AssertionConfig {
+  let platformIdentifier = 'unknown';
+  if (typeof navigator !== 'undefined') {
+    if (typeof navigator.userAgent === 'string') {
+      platformIdentifier = navigator.userAgent;
+    } else if (typeof navigator.platform === 'string') {
+      platformIdentifier = navigator.platform; // Deprecated, but used as a fallback
+    }
+  }
+
+  const metadata: SystemMetadata = {
+    tdf_spec_version: tdfSpecVersion,
+    creation_date: new Date().toISOString(),
+    sdk_version: `JS-${sdkVersion}`, // Prefixed to distinguish from Go SDK version
+    browser_user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : 'unknown',
+    platform: platformIdentifier,
+  };
+
+  const metadataJSON = JSON.stringify(metadata);
+
+  return {
+    id: 'system-metadata', // Consistent ID for this type of assertion
+    type: 'other', // General type for metadata assertions
+    scope: 'tdo', // Metadata typically applies to the TDF Data Object as a whole
+    appliesToState: 'unencrypted', // Metadata itself is not encrypted by this assertion's scope
+    statement: {
+      format: 'json',
+      schema: 'system-metadata-v1', // A schema name for this metadata
+      value: metadataJSON,
+    },
+  };
+}
+
 function concatenateUint8Arrays(array1: Uint8Array, array2: Uint8Array): Uint8Array {
   const combinedLength = array1.length + array2.length;
   const combinedArray = new Uint8Array(combinedLength);

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

@@ -31,6 +31,7 @@ export type EncryptStreamMiddleware = (
 
 export type SplitStep = {
   kas: string;
+  kid?: string;
   sid?: string;
 };
 
@@ -50,6 +51,7 @@ export type EncryptParams = {
   splitPlan?: SplitStep[];
   streamMiddleware?: EncryptStreamMiddleware;
   assertionConfigs?: AssertionConfig[];
+  systemMetadataAssertion?: boolean;
   defaultKASEndpoint?: string;
 
   // Preferred wrapping key algorithm. Used when KID resolution is not available.
@@ -499,6 +501,19 @@ class EncryptParamsBuilder {
     this._params.assertionConfigs = assertionConfigs;
     return this;
   }
+
+  /**
+   * Specifies whether a default system metadata assertion should be automatically
+   * included during the encryption process.
+   *
+   * @param {boolean} systemMetadataAssertion - True to include the system metadata assertion, false otherwise.
+   * @returns {EncryptParamsBuilder} The current instance of the EncryptParamsBuilder for method chaining.
+   * @see {@link getSystemMetadataAssertionConfig}
+   */
+  withSystemMetadataAssertion(systemMetadataAssertion: boolean): EncryptParamsBuilder {
+    this._params.systemMetadataAssertion = systemMetadataAssertion;
+    return this;
+  }
 }
 
 export type DecryptKeyMiddleware = (key: Binary) => Promise<Binary>;
@@ -523,6 +538,7 @@ export type DecryptParams = {
   concurrencyLimit?: number;
   noVerifyAssertions?: boolean;
   wrappingKeyAlgorithm?: KasPublicKeyAlgorithm;
+  fulfillableObligationFQNs?: string[];
 };
 
 /**