feat: add system metadata assertion (#630)

This pull request introduces a new feature to include system metadata assertions during the encryption process in the `tdf3` library. The changes add support for automatically generating and embedding metadata about the system environment into the manifest of encrypted files. This functionality is configurable and has been thoroughly tested with new unit tests.

### Feature: System Metadata Assertions

#### Core Implementation:
* **`lib/tdf3/src/assertions.ts`**: Added the `SystemMetadata` type to define the structure of system metadata, and implemented the `getSystemMetadataAssertionConfig` function to generate default metadata assertions. This includes details such as TDF specification version, SDK version, operating system, and browser user agent.
* **`lib/tdf3/src/tdf.ts`**: Modified the `writeStream` function to include system metadata assertions in the manifest if the `systemMetadataAssertion` flag is enabled in the encryption configuration.

#### Configuration Enhancements:
* **`lib/tdf3/src/client/builders.ts`**: Added the `systemMetadataAssertion` property to `EncryptParams` and a corresponding `withSystemMetadataAssertion` method in `EncryptParamsBuilder` for enabling this feature during encryption. [[1]](diffhunk://#diff-fa045a0a354fbc54f8447bbc5aeb39723e58b98150e278dc5584ee9309fdce6bR53) [[2]](diffhunk://#diff-fa045a0a354fbc54f8447bbc5aeb39723e58b98150e278dc5584ee9309fdce6bR503-R515)
* **`lib/tdf3/src/tdf.ts`**: Updated the `EncryptConfiguration` type to include the `systemMetadataAssertion` flag.

#### Client Integration:
* **`lib/tdf3/src/client/index.ts`**: Passed the `systemMetadataAssertion` flag to the encryption configuration within the `Client` class.

### Testing: Unit Tests for System Metadata Assertions
* **`lib/tests/mocha/encrypt-decrypt.spec.ts`**: Added a new test case to verify the inclusion and correctness of system metadata assertions in the manifest during encryption and decryption processes. This ensures that the metadata is correctly generated, embedded, and validated.

These changes enhance the encryption process by providing additional metadata for debugging, auditing, or compliance purposes, while maintaining flexibility through optional configuration.

Author: strantalis

lib/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';
@@ -229,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);

lib/tdf3/src/client/builders.ts

@@ -51,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.
@@ -500,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>;

lib/tdf3/src/client/index.ts

@@ -721,6 +721,7 @@ export class Client {
       keyForEncryption,
       keyForManifest,
       assertionConfigs: opts.assertionConfigs,
+      systemMetadataAssertion: opts.systemMetadataAssertion,
       tdfSpecVersion,
     };
 

lib/tdf3/src/tdf.ts

@@ -147,6 +147,7 @@ export type EncryptConfiguration = {
   keyForEncryption: KeyInfo;
   keyForManifest: KeyInfo;
   assertionConfigs?: AssertionConfig[];
+  systemMetadataAssertion?: boolean;
   tdfSpecVersion?: string;
 };
 
@@ -534,8 +535,24 @@ export async function writeStream(cfg: EncryptConfiguration): Promise<DecoratedR
         manifest.encryptionInformation.integrityInformation.segments = segmentInfos;
 
         manifest.encryptionInformation.method.isStreamable = true;
-
         const signedAssertions: assertions.Assertion[] = [];
+        if (cfg.systemMetadataAssertion) {
+          const systemMetadataConfigBase = assertions.getSystemMetadataAssertionConfig();
+          const signingKeyForSystemMetadata: AssertionKey = {
+            alg: 'HS256', // Default algorithm, can be configured if needed
+            key: new Uint8Array(cfg.keyForEncryption.unwrappedKeyBinary.asArrayBuffer()),
+          };
+          signedAssertions.push(
+            await assertions.CreateAssertion(
+              aggregateHash,
+              {
+                ...systemMetadataConfigBase, // Spread the properties from the base config
+                signingKey: signingKeyForSystemMetadata, // Add the signing key
+              },
+              cfg.tdfSpecVersion // Pass the TDF spec version
+            )
+          );
+        }
         if (cfg.assertionConfigs && cfg.assertionConfigs.length > 0) {
           await Promise.all(
             cfg.assertionConfigs.map(async (assertionConfig) => {

lib/tests/mocha/encrypt-decrypt.spec.ts

@@ -6,7 +6,12 @@ import { KasPublicKeyAlgorithm } from '../../src/access.js';
 import { AuthProvider, HttpRequest } from '../../src/auth/auth.js';
 import { AesGcmCipher, KeyInfo, SplitKey, WebCryptoService } from '../../tdf3/index.js';
 import { Client } from '../../tdf3/src/index.js';
-import { AssertionConfig, AssertionVerificationKeys } from '../../tdf3/src/assertions.js';
+import {
+  AssertionConfig,
+  AssertionVerificationKeys,
+  getSystemMetadataAssertionConfig,
+  Assertion,
+} from '../../tdf3/src/assertions.js';
 import { Scope } from '../../tdf3/src/client/builders.js';
 import { NetworkError } from '../../src/errors.js';
 
@@ -364,4 +369,124 @@ describe('encrypt decrypt test', async function () {
       });
     }
   }
+
+  it('encrypt-decrypt with system metadata assertion', async function () {
+    const cipher = new AesGcmCipher(WebCryptoService);
+    const encryptionInformation = new SplitKey(cipher);
+    const key1 = await encryptionInformation.generateKey();
+    const keyMiddleware = async () => ({ keyForEncryption: key1, keyForManifest: key1 });
+
+    const client = new Client.Client({
+      kasEndpoint: kasUrl,
+      platformUrl: kasUrl,
+      dpopKeys: Mocks.entityKeyPair(),
+      clientId: 'id',
+      authProvider,
+    });
+
+    const scope: Scope = {
+      dissem: ['[email protected]'],
+      attributes: [],
+    };
+
+    const encryptedStream = await client.encrypt({
+      metadata: Mocks.getMetadataObject(),
+      wrappingKeyAlgorithm: 'rsa:2048',
+      offline: true,
+      scope,
+      keyMiddleware,
+      source: new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(expectedVal));
+          controller.close();
+        },
+      }),
+      systemMetadataAssertion: true, // Enable the system metadata assertion
+    });
+
+    // Consume the stream into a buffer. This also ensures manifest population is complete.
+    const encryptedTdfBuffer = await encryptedStream.toBuffer();
+
+    // Verify the manifest for the system metadata assertion
+    const manifest = encryptedStream.manifest;
+    assert.isArray(manifest.assertions, 'Manifest assertions should be an array');
+    assert.lengthOf(manifest.assertions, 1, 'Should have one assertion for system metadata');
+
+    const systemAssertion = manifest.assertions.find(
+      (assertion: Assertion) => assertion.id === 'system-metadata'
+    );
+    assert.isDefined(systemAssertion, 'System metadata assertion should be found');
+    if (systemAssertion) {
+      assert.equal(systemAssertion.type, 'other', 'Assertion type should be "other"');
+      assert.equal(systemAssertion.scope, 'tdo', 'Assertion scope should be "tdo"');
+      assert.equal(systemAssertion.statement.format, 'json', 'Statement format should be "json"');
+      assert.equal(
+        systemAssertion.statement.schema,
+        'system-metadata-v1',
+        'Statement schema should be "system-metadata-v1"'
+      );
+
+      const metadataValue = JSON.parse(systemAssertion.statement.value);
+      assert.property(metadataValue, 'tdf_spec_version', 'Metadata should have tdfSpecVersion');
+      assert.property(metadataValue, 'creation_date', 'Metadata should have creationDate');
+      assert.property(metadataValue, 'sdk_version', 'Metadata should have sdkVersion');
+      assert.property(metadataValue, 'browser_user_agent', 'Metadata should have browserUserAgent');
+      assert.property(metadataValue, 'platform', 'Metadata should have platform');
+
+      // Compare Values
+      const systemMetadata = getSystemMetadataAssertionConfig();
+      assert.equal(systemMetadata.id, systemAssertion.id, 'ID should match');
+      assert.equal(systemMetadata.type, systemAssertion.type, 'Type should match');
+      assert.equal(systemMetadata.scope, systemAssertion.scope, 'Scope should match');
+      assert.equal(
+        systemMetadata.statement.format,
+        systemAssertion.statement.format,
+        'Statement format should match'
+      );
+      assert.equal(
+        systemMetadata.statement.schema,
+        systemAssertion.statement.schema,
+        'Statement schema should match'
+      );
+      assert.equal(
+        systemMetadata.appliesToState,
+        systemAssertion.appliesToState,
+        'AppliesToState should match'
+      );
+
+      // Parse statement.value and compare individual fields, ignoring creationDate for direct equality
+      const expectedMetadataValue = JSON.parse(systemMetadata.statement.value);
+      const actualMetadataValue = JSON.parse(systemAssertion.statement.value);
+
+      assert.isString(actualMetadataValue.creation_date, 'creation_date should be a string');
+      assert.isNotEmpty(actualMetadataValue.creation_date, 'creation_date should not be empty');
+      assert.equal(
+        actualMetadataValue.tdf_spec_version,
+        expectedMetadataValue.tdf_spec_version,
+        'tdf_spec_version should match'
+      );
+      assert.equal(
+        actualMetadataValue.sdk_version,
+        expectedMetadataValue.sdk_version,
+        'sdk_version should match'
+      );
+      assert.equal(
+        actualMetadataValue.browser_user_agent,
+        expectedMetadataValue.browser_user_agent,
+        'browser_user_agent should match'
+      );
+      assert.equal(
+        actualMetadataValue.platform,
+        expectedMetadataValue.platform,
+        'platform should match'
+      );
+    }
+
+    const decryptStream = await client.decrypt({
+      source: { type: 'buffer', location: encryptedTdfBuffer },
+    });
+
+    const { value: decryptedText } = await decryptStream.stream.getReader().read();
+    assert.equal(new TextDecoder().decode(decryptedText), expectedVal);
+  });
 });