@notabene/javascript-sdk 2.19.0 → 2.20.0-next.1

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

@@ -4,6 +4,7 @@ import type { DID, RefreshSource } from '../../types';
 import {
   ConnectionManager,
   type ConnectionStatus,
+  decryptCounterpartyAssistPayload,
   getRefreshResult,
   type TransactionType,
 } from '../connections';
@@ -53,6 +54,7 @@ const arbConnectionMetadata = fc.record({
   participants: fc.array(fc.string(), { minLength: 1 }), // At least one participant
   nodeUrl: fc.webUrl(),
   transactionType: fc.constantFrom<TransactionType>('withdraw', 'deposit'),
+  webhookUrl: fc.option(fc.webUrl(), { nil: undefined }),
 });
 
 describe('ConnectionManager', () => {
@@ -317,6 +319,7 @@ describe('ConnectionManager', () => {
     const refreshSource: RefreshSource = {
       url: 'https://test-endpoint.com',
       key: sealed.key,
+      id: 'test-id',
     };
 
     // Common metadata for all tests
@@ -385,6 +388,7 @@ describe('ConnectionManager', () => {
       const completedRefreshSource: RefreshSource = {
         url: 'https://test-endpoint.com',
         key: completedSealed.key,
+        id: 'test-id',
       };
 
       const mockResponse = createMockResponse(
@@ -435,3 +439,28 @@ describe('ConnectionManager', () => {
     });
   });
 });
+
+describe('decryptCounterpartyAssistPayload', () => {
+  it('round-trips a sealed payload back to the original object', async () => {
+    const original = { result: { ref: 'abc' }, tx: { amount: '10' } };
+    const sealed = await seal(original);
+
+    const decrypted = await decryptCounterpartyAssistPayload<typeof original>({
+      sealed: sealed.ciphertext,
+      key: sealed.key,
+    });
+
+    expect(decrypted).toEqual(original);
+  });
+
+  it('throws when the key is wrong', async () => {
+    const sealed = await seal({ a: 1 });
+    const other = await seal({ b: 2 });
+    await expect(
+      decryptCounterpartyAssistPayload({
+        sealed: sealed.ciphertext,
+        key: other.key,
+      }),
+    ).rejects.toThrow();
+  });
+});

package/src/utils/connections.ts

@@ -24,6 +24,14 @@ export interface ConnectionMetadata {
   readonly participants: readonly string[];
   readonly transactionType: TransactionType;
   readonly locale?: string;
+  /**
+   * Delivery target for Counterparty Assist completion/closure webhooks.
+   * Sent and stored as plaintext so the connection can route the event, so do not
+   * embed secrets (e.g. `?token=`) in this URL. Webhook payloads carry the encrypted
+   * `sealed` blob, whose successful decryption is itself an authenticity check;
+   * signed delivery is provided by the future Svix-backed pipeline.
+   */
+  readonly webhookUrl?: string;
 }
 
 export interface ConnectionResponse<T extends ComponentRequest> {
@@ -61,7 +69,7 @@ export type ConnectionResult<T extends ComponentRequest> =
  * @returns Promise resolving to connection result with decrypted data
  */
 export async function getRefreshResult<T extends ComponentRequest>(
-  refreshSource: RefreshSource,
+  refreshSource: Pick<RefreshSource, 'url' | 'key'>,
 ): Promise<ConnectionResult<T>> {
   const response = await fetch(refreshSource.url, {
     method: 'GET',
@@ -109,6 +117,22 @@ export async function getRefreshResult<T extends ComponentRequest>(
   };
 }
 
+/**
+ * Decrypt a Counterparty Assist webhook payload with the key the VASP captured
+ * at connection creation. Single call, no network fetch (the webhook already
+ * carried the ciphertext).
+ * @public
+ */
+export async function decryptCounterpartyAssistPayload<T>({
+  sealed,
+  key,
+}: {
+  sealed: string;
+  key: string;
+}): Promise<T> {
+  return unseal<T>({ ciphertext: sealed, key });
+}
+
 /**
  * Manages encrypted connections using Cloudflare Durable Objects
  */