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

package/docs/types/type-aliases/VASPOptions.md

@@ -26,4 +26,4 @@ Options for which VASPs to be searchable
 
 ## Defined in
 
-[types.ts:749](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/80aada173fac6a9b5f05869abafa3c1c6cc56aa9/src/types.ts#L749)
+[types.ts:777](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/27e5c6c27d8a3a0bdafefd6e32c1654e964838a3/src/types.ts#L777)

package/docs/types/type-aliases/ValidationError.md

@@ -22,4 +22,4 @@ Validation error
 
 ## Defined in
 
-[types.ts:705](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/80aada173fac6a9b5f05869abafa3c1c6cc56aa9/src/types.ts#L705)
+[types.ts:733](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/27e5c6c27d8a3a0bdafefd6e32c1654e964838a3/src/types.ts#L733)

package/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.8.0-next.4",
+  "version": "2.8.0-next.6",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/src/notabene.ts

@@ -73,6 +73,13 @@ import { type MessageCallback } from './utils/MessageEventManager';
 import { decodeFragmentToObject, encodeObjectToFragment } from './utils/urls';
 // Must be exported for React Native SDK to use
 export { default as EmbeddedComponent } from './components/EmbeddedComponent';
+export {
+  ConnectionManager,
+  type ConnectionData,
+  type ConnectionMetadata,
+  type ConnectionResponse,
+  type TransactionType,
+} from './utils/connections';
 export {
   AgentType,
   CMType,

package/src/types.ts

@@ -5,6 +5,7 @@ import type {
   ISODate,
   IVMS101,
   NationalIdentification,
+  NationalIdentifierTypeCode,
   Originator,
 } from './ivms/types';
 
@@ -392,13 +393,31 @@ export type NaturalPersonFieldName =
   | 'countryOfResidence'; // ISO Country code of residence of Natural Person
 
 /**
- * Field properties by field name for Natural persons
+ * Field properties for national identifier type selection
  * @public
  */
-export type NaturalPersonFields = {
-  [name in NaturalPersonFieldName]?: FieldOptions;
+export type NationalIdentifierTypeFieldOptions = {
+  values?: NationalIdentifierTypeCode[];
 };
 
+/**
+ * Field properties for natural person fields
+ * @public
+ */
+export type NaturalPersonFields = Partial<{
+  name: FieldOptions;
+  website: FieldOptions;
+  email: FieldOptions;
+  phone: FieldOptions;
+  geographicAddress: FieldOptions;
+  nationalIdentification: FieldOptions & {
+    nationalIdentifierType: NationalIdentifierTypeFieldOptions;
+  };
+  dateOfBirth: FieldOptions;
+  placeOfBirth: FieldOptions;
+  countryOfResidence: FieldOptions;
+}>;
+
 /**
  * Interface representing a legal entity (organization/company) involved in a transaction
  *
@@ -438,12 +457,21 @@ export type LegalPersonFieldName =
   | 'countryOfRegistration'; // ISO Country code of registration of Legal Person
 
 /**
- * Field properties by field name
+ * Field properties for legal person fields
  * @public
  */
-export type LegalPersonFields = {
-  [name in LegalPersonFieldName]?: FieldOptions;
-};
+export type LegalPersonFields = Partial<{
+  name: FieldOptions;
+  lei: FieldOptions;
+  website: FieldOptions;
+  email: FieldOptions;
+  phone: FieldOptions;
+  geographicAddress: FieldOptions;
+  nationalIdentification: FieldOptions & {
+    nationalIdentifierType: NationalIdentifierTypeFieldOptions;
+  };
+  countryOfRegistration: FieldOptions;
+}>;
 
 /**
  * Fields specific to the originator of a transaction

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()}`);
+    }
+  }
+}