@notabene/javascript-sdk 2.8.0-next.4 → 2.8.0-next.5

package/src/utils/__tests__/connections.test.ts

@@ -0,0 +1,284 @@
+import fc from 'fast-check';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { DID } from '../../types';
+import { ConnectionManager, TransactionType } from '../connections';
+import { seal } from '../encryption';
+
+// Mock fetch globally
+const fetchMock = vi.fn();
+global.fetch = fetchMock;
+
+// Helper to generate valid DID strings
+const arbDID = fc
+  .tuple(fc.string(), fc.string())
+  .map(([method, id]) => `did:${method}:${id}` as DID);
+
+// Test helper to create arbitrary ComponentRequests
+const arbComponentRequest = fc.record({
+  tx: fc.record({
+    requestId: fc.option(fc.uuid(), { nil: undefined }),
+    customer: fc.option(
+      fc.record({
+        name: fc.string(),
+        email: fc.option(fc.string(), { nil: undefined }),
+        phone: fc.option(fc.string(), { nil: undefined }),
+        type: fc.constant(undefined), // Optional PersonType
+        accountNumber: fc.option(fc.string(), { nil: undefined }),
+        did: fc.option(arbDID, { nil: undefined }),
+        verified: fc.option(fc.boolean(), { nil: undefined }),
+        website: fc.option(fc.webUrl(), { nil: undefined }),
+        geographicAddress: fc.option(fc.constant(undefined), {
+          nil: undefined,
+        }),
+        nationalIdentification: fc.option(fc.constant(undefined), {
+          nil: undefined,
+        }),
+      }),
+      { nil: undefined },
+    ),
+  }),
+  authToken: fc.option(fc.string(), { nil: undefined }),
+  txOptions: fc.option(fc.record({}), { nil: undefined }),
+});
+
+// New arbitrary for ConnectionMetadata
+const arbConnectionMetadata = fc.record({
+  participants: fc.array(fc.string(), { minLength: 1 }), // At least one participant
+  nodeUrl: fc.webUrl(),
+  transactionType: fc.constantFrom<TransactionType>('withdraw', 'deposit'),
+});
+
+describe('ConnectionManager', () => {
+  let manager: ConnectionManager;
+  const testEndpoint = 'https://test-endpoint.com';
+
+  beforeEach(() => {
+    manager = new ConnectionManager(testEndpoint);
+    fetchMock.mockReset();
+  });
+
+  describe('create', () => {
+    it('should successfully create a new connection', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          arbComponentRequest,
+          arbConnectionMetadata,
+          async (request, metadata) => {
+            // Mock successful response
+            const mockResponse = {
+              id: 'test-id',
+              version: 1,
+              metadata,
+              sealed: ['encrypted-data'],
+            };
+
+            fetchMock.mockResolvedValueOnce({
+              ok: true,
+              json: async () => mockResponse,
+            });
+
+            const result = await manager.create(request, metadata);
+
+            // Verify fetch was called correctly
+            expect(fetchMock).toHaveBeenCalledWith(testEndpoint, {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+              },
+              body: expect.any(String),
+            });
+
+            // Verify response structure
+            expect(result).toEqual({
+              id: mockResponse.id,
+              metadata: mockResponse.metadata,
+              version: mockResponse.version,
+              data: request,
+              key: expect.any(String),
+            });
+          },
+        ),
+      );
+    });
+
+    it('should throw error on failed creation', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          arbComponentRequest,
+          arbConnectionMetadata,
+          async (request, metadata) => {
+            // Mock failed response
+            fetchMock.mockResolvedValueOnce({
+              ok: false,
+              text: async () => 'Creation failed',
+            });
+
+            await expect(manager.create(request, metadata)).rejects.toThrow(
+              'Failed to create connection',
+            );
+          },
+        ),
+      );
+    });
+  });
+
+  describe('update', () => {
+    it('should successfully update an existing connection', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.uuid(),
+          arbComponentRequest,
+          fc.integer(),
+          async (id, request, version) => {
+            // Mock successful response
+            const mockResponse = {
+              id,
+              metadata: arbConnectionMetadata,
+              version: version + 1,
+              sealed: ['new-encrypted-data'],
+            };
+
+            fetchMock.mockResolvedValueOnce({
+              ok: true,
+              json: async () => mockResponse,
+            });
+
+            const result = await manager.update(id, request, version);
+
+            // Verify fetch was called correctly
+            expect(fetchMock).toHaveBeenCalledWith(`${testEndpoint}/${id}`, {
+              method: 'PATCH',
+              headers: {
+                'Content-Type': 'application/json',
+              },
+              body: expect.any(String),
+            });
+
+            // Verify response structure
+            expect(result).toEqual({
+              id: mockResponse.id,
+              version: mockResponse.version,
+              metadata: mockResponse.metadata,
+              data: request,
+              key: expect.any(String),
+            });
+          },
+        ),
+      );
+    });
+
+    it('should throw error on failed update', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.uuid(),
+          arbComponentRequest,
+          fc.integer(),
+          async (id, request, version) => {
+            // Mock failed response
+            fetchMock.mockResolvedValueOnce({
+              ok: false,
+              text: async () => 'Update failed',
+            });
+
+            await expect(manager.update(id, request, version)).rejects.toThrow(
+              'Failed to update connection',
+            );
+          },
+        ),
+      );
+    });
+  });
+
+  describe('get', () => {
+    it('should successfully retrieve and decrypt connection data', async () => {
+      // Create a real sealed object to use in our test
+      const testData = { requestId: 'test-123' };
+      const sealed = await seal(testData);
+
+      await fc.assert(
+        fc.asyncProperty(fc.uuid(), async (id) => {
+          // Mock successful response with real encrypted data
+          const mockResponse = {
+            id,
+            version: 1,
+            metadata: arbConnectionMetadata,
+            sealed: [sealed.ciphertext], // Use the real ciphertext
+          };
+
+          fetchMock.mockResolvedValueOnce({
+            ok: true,
+            json: async () => mockResponse,
+          });
+
+          const result = await manager.get(id, sealed.key); // Use the matching key
+
+          // Verify fetch was called correctly
+          expect(fetchMock).toHaveBeenCalledWith(`${testEndpoint}/${id}`, {
+            method: 'GET',
+          });
+
+          // Verify response structure
+          expect(result).toEqual({
+            id: mockResponse.id,
+            version: mockResponse.version,
+            metadata: mockResponse.metadata,
+            data: testData, // Should match our original test data
+            key: sealed.key,
+          });
+        }),
+      );
+    });
+
+    it('should throw error on failed retrieval', async () => {
+      await fc.assert(
+        fc.asyncProperty(fc.uuid(), fc.string(), async (id, key) => {
+          // Mock failed response
+          fetchMock.mockResolvedValueOnce({
+            ok: false,
+            text: async () => 'Retrieval failed',
+          });
+
+          await expect(manager.get(id, key)).rejects.toThrow(
+            'Failed to get connection',
+          );
+        }),
+      );
+    });
+  });
+
+  describe('close', () => {
+    it('should successfully close a connection', async () => {
+      await fc.assert(
+        fc.asyncProperty(fc.uuid(), async (id) => {
+          // Mock successful response
+          fetchMock.mockResolvedValueOnce({
+            ok: true,
+          });
+
+          await manager.close(id);
+
+          // Verify fetch was called correctly
+          expect(fetchMock).toHaveBeenCalledWith(`${testEndpoint}/${id}`, {
+            method: 'DELETE',
+          });
+        }),
+      );
+    });
+
+    it('should throw error on failed closure', async () => {
+      await fc.assert(
+        fc.asyncProperty(fc.uuid(), async (id) => {
+          // Mock failed response
+          fetchMock.mockResolvedValueOnce({
+            ok: false,
+            text: async () => 'Closure failed',
+          });
+
+          await expect(manager.close(id)).rejects.toThrow(
+            'Failed to close connection',
+          );
+        }),
+      );
+    });
+  });
+});

package/src/utils/__tests__/encryption.test.ts

@@ -0,0 +1,79 @@
+import * as fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import { Agent, AgentType } from '../../types';
+import { seal, unseal } from '../encryption';
+
+// Helper to validate that two objects are deeply equal
+function deepEqual(
+  obj1: Record<string, unknown>,
+  obj2: Record<string, unknown>,
+): boolean {
+  return JSON.stringify(obj1) === JSON.stringify(obj2);
+}
+
+describe('normal tests', () => {
+  it('should correctly seal and unseal a Javascript object', async () => {
+    const agent: Agent = { type: AgentType.VASP, did: 'did:web:hello.com' };
+    const sealed = await seal<Agent>(agent);
+    const unsealed = await unseal<Agent>(sealed);
+    expect(unsealed).toEqual(agent);
+  });
+});
+describe('seal and unseal functions with combined IV and ciphertext', () => {
+  it('should correctly seal and unseal a JavaScript object', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.object(), // Generate random objects
+        async (originalObject) => {
+          const { ciphertext, key } =
+            await seal<Record<string, unknown>>(originalObject); // Seal the object
+          const unsealedObject = await unseal<Record<string, unknown>>({
+            ciphertext,
+            key,
+          }); // Unseal the ciphertext
+
+          // Validate that the unsealed object matches the original
+          expect(deepEqual(originalObject, unsealedObject)).toBe(true);
+        },
+      ),
+    );
+  });
+
+  it('should throw an error if the key is invalid', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.object(),
+        fc.string(), // Generate a random invalid key
+        async (originalObject, invalidKey) => {
+          const { ciphertext } =
+            await seal<Record<string, unknown>>(originalObject);
+
+          await expect(
+            unseal<Record<string, unknown>>({ ciphertext, key: invalidKey }),
+          ).rejects.toThrowError();
+        },
+      ),
+    );
+  });
+
+  it('should throw an error if the ciphertext is tampered with', async () => {
+    await fc.assert(
+      fc.asyncProperty(fc.object(), async (originalObject) => {
+        const { ciphertext, key } =
+          await seal<Record<string, unknown>>(originalObject);
+
+        // Tamper with the ciphertext
+        const tamperedCiphertext =
+          ciphertext.slice(0, -1) + (ciphertext.at(-1) === 'A' ? 'B' : 'A');
+
+        // Expect decryption to fail
+        await expect(
+          unseal<Record<string, unknown>>({
+            ciphertext: tamperedCiphertext,
+            key,
+          }),
+        ).rejects.toThrowError();
+      }),
+    );
+  });
+});

package/src/utils/connections.ts

@@ -0,0 +1,174 @@
+import type { ComponentRequest, TransactionOptions, UUID } from '../types';
+import { seal, unseal } from './encryption';
+
+export type TransactionType = 'withdraw' | 'deposit';
+export interface ConnectionData<T extends ComponentRequest> {
+  tx: T;
+  authToken?: string;
+  txOptions?: TransactionOptions;
+}
+
+export interface ConnectionMetadata {
+  nodeUrl?: string;
+  participants: string[];
+  transactionType: TransactionType;
+}
+export interface ConnectionResponse<T extends ComponentRequest> {
+  id: UUID;
+  version: number;
+  metadata: ConnectionMetadata;
+  data: ConnectionData<T>;
+  key: string;
+}
+
+/**
+ * Manages encrypted connections using Cloudflare Durable Objects
+ */
+export class ConnectionManager {
+  private endpoint: string;
+
+  constructor(endpoint: string) {
+    this.endpoint = endpoint;
+  }
+
+  /**
+   * Creates a new encrypted connection
+   * @param data The component request data to encrypt and store
+   * @param participants Array of participant identifiers
+   * @returns Promise resolving to connection details including ID, version, and encryption key
+   */
+  async create<T extends ComponentRequest>(
+    data: ConnectionData<T>,
+    metadata: ConnectionMetadata,
+  ): Promise<ConnectionResponse<T>> {
+    // Encrypt the data
+    const sealed = await seal(data);
+
+    // Prepare the request body
+    const body = {
+      metadata,
+      sealed: sealed.ciphertext,
+    };
+
+    // Create the connection
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to create connection: ${await response.text()}`);
+    }
+
+    const result = await response.json();
+
+    return {
+      id: result.id,
+      version: result.version,
+      metadata: metadata,
+      data: data,
+      key: sealed.key,
+    };
+  }
+
+  /**
+   * Updates an existing connection with new encrypted data
+   * @param id Connection ID
+   * @param data New data to encrypt and store
+   * @param version Current version number
+   * @returns Promise resolving to updated connection details including new encryption key
+   */
+  async update<T extends ComponentRequest>(
+    id: UUID,
+    data: ConnectionData<T>,
+    version: number,
+  ): Promise<ConnectionResponse<T>> {
+    // Encrypt the new data
+    const sealed = await seal(data);
+
+    // Prepare the request body
+    const body = {
+      sealed: sealed.ciphertext,
+      version,
+    };
+
+    // Update the connection
+    const response = await fetch(`${this.endpoint}/${id}`, {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to update connection: ${await response.text()}`);
+    }
+
+    const result = await response.json();
+
+    return {
+      id: result.id,
+      metadata: result.metadata,
+      version: result.version,
+      data: data,
+      key: sealed.key,
+    };
+  }
+
+  /**
+   * Retrieves and decrypts connection data
+   * @param id Connection ID
+   * @param key Encryption key from previous create/update operation
+   * @returns Promise resolving to connection details including decrypted data
+   */
+  async get<T extends ComponentRequest>(
+    id: UUID,
+    key: string,
+  ): Promise<ConnectionResponse<T>> {
+    // Get the connection data
+    const response = await fetch(`${this.endpoint}/${id}`, {
+      method: 'GET',
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to get connection: ${await response.text()}`);
+    }
+
+    const result = await response.json();
+
+    // Get the latest sealed data
+    const latestSealed = result.sealed[result.sealed.length - 1];
+
+    // Decrypt the data
+    const data = await unseal<ConnectionData<T>>({
+      ciphertext: latestSealed,
+      key,
+    });
+
+    return {
+      id: result.id,
+      version: result.version,
+      metadata: result.metadata,
+      data,
+      key,
+    };
+  }
+
+  /**
+   * Closes a connection
+   * @param id Connection ID
+   */
+  async close(id: UUID): Promise<void> {
+    const response = await fetch(`${this.endpoint}/${id}`, {
+      method: 'DELETE',
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to close connection: ${await response.text()}`);
+    }
+  }
+}

package/src/utils/encryption.ts

@@ -0,0 +1,111 @@
+/**
+ * Result of a sealing operation, containing ciphertext and encryption key.
+ */
+export interface Sealed {
+  /** Base64-encoded ciphertext combined with initialization vector (IV) */
+  ciphertext: string;
+  /** Base64-encoded encryption key */
+  key: string;
+}
+
+/**
+ * Encrypts an object using AES-GCM encryption.
+ * @template T Type of data to encrypt
+ * @param data Data to encrypt
+ * @returns Promise resolving to a Sealed object containing ciphertext and key
+ */
+export async function seal<T>(data: T): Promise<Sealed> {
+  // Convert the object to a JSON string
+  const plaintext = JSON.stringify(data);
+  const encoder = new TextEncoder();
+
+  // Generate a random encryption key and IV
+  const rawKey = crypto.getRandomValues(new Uint8Array(32)); // 256-bit key
+  const key = await crypto.subtle.importKey(
+    'raw',
+    rawKey,
+    { name: 'AES-GCM' },
+    false,
+    ['encrypt'],
+  );
+
+  const iv = crypto.getRandomValues(new Uint8Array(12)); // 96-bit IV
+
+  // Encrypt the plaintext
+  const ciphertextBuffer = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv: iv },
+    key,
+    encoder.encode(plaintext),
+  );
+
+  // Combine the IV and ciphertext, separated by `-`
+  const ciphertext = `${arrayBufferToBase64(iv)}-${arrayBufferToBase64(ciphertextBuffer)}`;
+
+  // Return the base64 encoded ciphertext and key
+  return {
+    ciphertext,
+    key: arrayBufferToBase64(rawKey),
+  };
+}
+
+/**
+ * Decrypts previously sealed object.
+ * @template T Type of data that was encrypted
+ * @param sealed Sealed object containing ciphertext and key
+ * @returns Promise resolving to the original decrypted data
+ */
+
+export async function unseal<T>({ ciphertext, key }: Sealed): Promise<T> {
+  // Split the IV and the ciphertext
+  const [ivBase64, ciphertextBase64] = ciphertext.split('-');
+
+  // Decode the key, IV, and ciphertext
+  const rawKey = new Uint8Array(
+    atob(key)
+      .split('')
+      .map((c) => c.charCodeAt(0)),
+  );
+  const iv = base64ToUint8Array(ivBase64);
+  const ciphertextBuffer = base64ToUint8Array(ciphertextBase64);
+
+  // Import the key
+  const keyObj = await crypto.subtle.importKey(
+    'raw',
+    rawKey,
+    { name: 'AES-GCM' },
+    false,
+    ['decrypt'],
+  );
+
+  // Decrypt the ciphertext
+  const decoder = new TextDecoder();
+  const plaintextBuffer = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv: new Uint8Array(iv) },
+    keyObj,
+    ciphertextBuffer,
+  );
+
+  // Parse and return the original object
+  return JSON.parse(decoder.decode(plaintextBuffer));
+}
+
+// Utility function to convert ArrayBuffer to Base64
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const uint8Array = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < uint8Array.length; i++) {
+    binary += String.fromCharCode(uint8Array[i]);
+  }
+  return btoa(binary);
+}
+
+// Utility function to convert Base64 to ArrayBuffer
+
+function base64ToUint8Array(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const buffer = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    buffer[i] = binary.charCodeAt(i);
+  }
+  return buffer;
+}