@novasamatech/host-container 0.4.0

package/README.md

@@ -0,0 +1,133 @@
+# @novasamatech/host-container
+
+A robust solution for hosting and managing decentralized applications (dapps) within the Polkadot ecosystem.
+
+## Overview
+
+Host container provides the infrastructure layer for securely embedding and communicating with third-party dapps.
+It handles the isolation boundary, message routing, lifecycle management, and security concerns inherent in hosting untrusted web content.
+
+## Installation
+
+```shell
+npm install @novasamatech/host-container --save -E
+```
+
+### Basic Container Setup
+
+```ts
+import { createContainer, createIframeProvider } from '@novasamatech/host-container';
+
+const iframe = document.createElement('iframe');
+
+const provider = createIframeProvider({
+  iframe,
+  url: 'https://dapp.example.com'
+});
+const container = createContainer(provider);
+
+document.body.appendChild(iframe);
+```
+
+### Accounts handling
+
+To handle account requests and subscriptions you can call `handleAccounts` method:
+
+```ts
+container.handleAccounts({
+  async get() {
+    // return injected accounts
+    return [];
+  },
+  subscribe(callback) {
+    // subscribe to account changes
+    
+    callback([]);
+    return () => {
+      // unsubscribe
+    };
+  },
+});
+```
+
+In this case you also should handle sign requests:
+
+```ts
+container.handleSignRequest({
+  signRaw(raw) {
+    // return signed payload based on raw data
+    return {
+      id: 0,
+      signature: '0x...',
+      signedTransaction: '0x...',
+    }
+  },
+  signPayload(payload) {
+    // return signed payload based on sign payload
+    return {
+      id: 0,
+      signature: '0x...',
+      signedTransaction: '0x...',
+    }
+  },
+  createTransaction(payload) {
+    // return full signed transaction
+    return '0x0000'
+  }
+});
+```
+
+### PAPI provider support
+
+Host container supports [PAPI](https://papi.how/) requests redirecting from product to host container.
+It can be useful to deduplicate socket connections or light client instances between multiple dapps.
+
+To support this feature you should add two additional handlers to container:
+
+#### Chain support check
+```ts
+const polkadotGenesisHash = '0x...';
+
+container.handleChainSupportCheck(async (genesisHash) => {
+  return genesisHash === polkadotGenesisHash;
+});
+```
+
+#### Provider implementation
+
+```ts
+import { getWsProvider } from 'polkadot-api/ws-provider';
+
+const polkadotGenesisHash = '0x...';
+const endpoint = 'wss://...';
+const provider = getWsProvider(endpoint);
+
+container.connectToPapiProvider(polkadotGenesisHash, provider);
+```
+
+### Additional metadata sync
+
+#### Receiving connection status
+
+```ts
+const unsubscribe = container.subscribeConnectionStatus((status) => {
+  console.log('connection status changed', status);
+});
+```
+
+#### Receiving dapp location change
+
+```ts
+const unsubscribe = container.subscribeLocationChange((location) => {
+  console.log('dapp location changed:', location);
+});
+```
+
+### Known pitfalls
+
+#### CSP error on iframe loading
+If dapp is hosted on different domain than container and uses https, you should add this meta tag to your host application html:
+
+```html
+<meta http-equiv="Content-Security-Policy" content="upgrade-insecure-requests">
+```

package/dist/createComplexSubscriber.d.ts

@@ -0,0 +1,12 @@
+import type { MessageType, PickMessagePayload, Transport } from '@novasamatech/host-api';
+type Subscriber<Response extends MessageType> = (callback: (response: PickMessagePayload<Response>) => void) => VoidFunction;
+type Params<SubscribeRequest extends MessageType, Response extends MessageType> = {
+    transport: Transport;
+    subscribeRequest: SubscribeRequest;
+    unsubscribeRequest: MessageType;
+    getSubscriber(): Subscriber<Response>;
+};
+export declare function createComplexSubscriber<SubscribeRequest extends MessageType, Response extends MessageType>({ transport, subscribeRequest, unsubscribeRequest, getSubscriber, }: Params<SubscribeRequest, Response>): {
+    replaceSubscriber: () => void;
+};
+export {};

package/dist/createComplexSubscriber.js

@@ -0,0 +1,31 @@
+export function createComplexSubscriber({ transport, subscribeRequest, unsubscribeRequest, getSubscriber, }) {
+    let unsubscribe = null;
+    let id = null;
+    const replaceSubscriber = () => {
+        if (unsubscribe) {
+            unsubscribe();
+        }
+        const subscriber = getSubscriber();
+        unsubscribe = subscriber(value => {
+            transport.postMessage(id ?? '_', value);
+        });
+    };
+    transport.subscribe(subscribeRequest, async (requestId) => {
+        id = requestId;
+        if (!unsubscribe) {
+            const subscriber = getSubscriber();
+            unsubscribe = subscriber(value => {
+                transport.postMessage(id ?? '_', value);
+            });
+        }
+        transport.subscribe(unsubscribeRequest, async () => {
+            if (unsubscribe) {
+                unsubscribe();
+                unsubscribe = null;
+            }
+        });
+    });
+    return {
+        replaceSubscriber,
+    };
+}

package/dist/createContainer.d.ts

@@ -0,0 +1,30 @@
+import type { ConnectionStatus, HexString, InjectedAccountSchema, TransportProvider, TxPayloadV1 } from '@novasamatech/host-api';
+import type { SignerPayloadJSON, SignerPayloadRaw, SignerResult } from '@polkadot/types/types';
+import type { JsonRpcProvider } from '@polkadot-api/json-rpc-provider';
+type ContainerHandlers = {
+    accounts: {
+        get(): Promise<InjectedAccountSchema[]>;
+        subscribe(callback: (accounts: InjectedAccountSchema[]) => void): VoidFunction;
+    };
+    sign: {
+        signRaw(raw: SignerPayloadRaw): Promise<SignerResult>;
+        signPayload(payload: SignerPayloadJSON): Promise<SignerResult>;
+        createTransaction(payload: TxPayloadV1): Promise<HexString>;
+    };
+    chainSupport(chainId: HexString): Promise<boolean>;
+};
+type Params = {
+    handshakeTimeout: number;
+};
+export type Container = ReturnType<typeof createContainer>;
+export declare function createContainer(provider: TransportProvider, params?: Params): {
+    connectToPapiProvider(chainId: HexString, provider: JsonRpcProvider): VoidFunction;
+    handleAccounts(handler: ContainerHandlers["accounts"]): void;
+    handleSignRequest(handler: ContainerHandlers["sign"]): void;
+    handleChainSupportCheck(handler: ContainerHandlers["chainSupport"]): void;
+    isReady(): Promise<boolean>;
+    subscribeLocationChange(callback: (location: string) => void): VoidFunction;
+    subscribeConnectionStatus(callback: (connectionStatus: ConnectionStatus) => void): VoidFunction;
+    dispose(): void;
+};
+export {};

package/dist/createContainer.js

@@ -0,0 +1,188 @@
+import { createTransport } from '@novasamatech/host-api';
+import { createComplexSubscriber } from './createComplexSubscriber';
+function formatError(e) {
+    const message = e instanceof Error ? e.message : typeof e === 'string' ? e : 'Unknown error';
+    return { tag: 'error', value: message };
+}
+const defaultHandlers = {
+    accounts: {
+        get: async () => [],
+        subscribe: () => () => {
+            /* empty */
+        },
+    },
+    sign: {
+        signRaw: () => Promise.reject(new Error('signRaw is not implemented')),
+        signPayload: () => Promise.reject(new Error('signPayload is not implemented')),
+        createTransaction: () => Promise.reject(new Error('createTransaction is not implemented')),
+    },
+    chainSupport: async () => false,
+};
+export function createContainer(provider, params) {
+    const transport = createTransport(provider, { handshakeTimeout: params?.handshakeTimeout });
+    if (!transport.isCorrectEnvironment()) {
+        throw new Error('Transport is not available: dapp provider has incorrect environment');
+    }
+    const externalHandlers = {};
+    // account subscription
+    transport.handleMessage('getAccountsRequestV1', async () => {
+        try {
+            const handler = externalHandlers.accounts ?? defaultHandlers.accounts;
+            const accounts = await handler.get();
+            return {
+                tag: 'getAccountsResponseV1',
+                value: { tag: 'success', value: accounts },
+            };
+        }
+        catch (e) {
+            return {
+                tag: 'getAccountsResponseV1',
+                value: formatError(e),
+            };
+        }
+    });
+    const accountSubscriber = transport
+        ? createComplexSubscriber({
+            transport,
+            subscribeRequest: 'accountSubscriptionV1',
+            unsubscribeRequest: 'accountUnsubscriptionV1',
+            getSubscriber() {
+                return callback => {
+                    const subscriber = externalHandlers.accounts?.subscribe ?? defaultHandlers.accounts.subscribe;
+                    return subscriber(accounts => {
+                        callback({
+                            tag: 'getAccountsResponseV1',
+                            value: { tag: 'success', value: accounts },
+                        });
+                    });
+                };
+            },
+        })
+        : null;
+    // sign subscription
+    transport.handleMessage('signRawRequestV1', async (message) => {
+        try {
+            const signRaw = externalHandlers.sign?.signRaw ?? defaultHandlers.sign.signRaw;
+            const result = await signRaw(message);
+            return {
+                tag: 'signResponseV1',
+                value: { tag: 'success', value: result },
+            };
+        }
+        catch (e) {
+            return {
+                tag: 'signResponseV1',
+                value: formatError(e),
+            };
+        }
+    });
+    transport.handleMessage('signPayloadRequestV1', async (message) => {
+        try {
+            const signPayload = externalHandlers.sign?.signPayload ?? defaultHandlers.sign.signPayload;
+            const result = await signPayload(message);
+            return {
+                tag: 'signResponseV1',
+                value: { tag: 'success', value: result },
+            };
+        }
+        catch (e) {
+            return {
+                tag: 'signResponseV1',
+                value: formatError(e),
+            };
+        }
+    });
+    transport.handleMessage('createTransactionRequestV1', async (message) => {
+        try {
+            const createTransaction = externalHandlers.sign?.createTransaction ?? defaultHandlers.sign.createTransaction;
+            const result = await createTransaction(message);
+            return {
+                tag: 'createTransactionResponseV1',
+                value: { tag: 'success', value: result },
+            };
+        }
+        catch (e) {
+            return {
+                tag: 'createTransactionResponseV1',
+                value: formatError(e),
+            };
+        }
+    });
+    // chain support subscription
+    transport.handleMessage('supportFeatureRequestV1', async (message) => {
+        if (message.tag === 'chain') {
+            try {
+                const checkChainSupport = externalHandlers.chainSupport ?? defaultHandlers.chainSupport;
+                const result = await checkChainSupport(message.value.chainId);
+                return {
+                    tag: 'supportFeatureResponseV1',
+                    value: {
+                        tag: 'success',
+                        value: { tag: 'chain', value: { chainId: message.value.chainId, result } },
+                    },
+                };
+            }
+            catch (e) {
+                return {
+                    tag: 'supportFeatureResponseV1',
+                    value: formatError(e),
+                };
+            }
+        }
+    });
+    function init() {
+        // init status subscription
+        transport.isReady();
+    }
+    return {
+        connectToPapiProvider(chainId, provider) {
+            init();
+            let connection = null;
+            return transport.handleMessage('papiProviderSendMessageV1', async (message) => {
+                if (!connection) {
+                    connection = provider(message => {
+                        transport.postMessage('_', {
+                            tag: 'papiProviderReceiveMessageV1',
+                            value: { tag: 'success', value: { chainId, message } },
+                        });
+                    });
+                }
+                if (message.chainId === chainId) {
+                    connection.send(message.message);
+                }
+            });
+        },
+        handleAccounts(handler) {
+            init();
+            externalHandlers.accounts = handler;
+            accountSubscriber?.replaceSubscriber();
+        },
+        handleSignRequest(handler) {
+            init();
+            externalHandlers.sign = handler;
+        },
+        handleChainSupportCheck(handler) {
+            init();
+            externalHandlers.chainSupport = handler;
+        },
+        isReady() {
+            return transport.isReady();
+        },
+        subscribeLocationChange(callback) {
+            init();
+            return transport.subscribe('locationChangedV1', async (location) => {
+                callback(location);
+            });
+        },
+        subscribeConnectionStatus(callback) {
+            // this specific order exists because container should report all connection statuses including "disconnected",
+            // which immediately got changed to "connecting" after init() call.
+            const unsubscribe = transport.onConnectionStatusChange(callback);
+            init();
+            return unsubscribe;
+        },
+        dispose() {
+            transport.dispose();
+        },
+    };
+}

package/dist/createIframeProvider.d.ts

@@ -0,0 +1,8 @@
+import type { Logger, TransportProvider } from '@novasamatech/host-api';
+type Params = {
+    iframe: HTMLIFrameElement;
+    url: string;
+    logger?: Logger;
+};
+export declare function createIframeProvider({ iframe, url, logger }: Params): TransportProvider;
+export {};

package/dist/createIframeProvider.js

@@ -0,0 +1,87 @@
+import { createDefaultLogger } from '@novasamatech/host-api';
+function hasWindow() {
+    try {
+        return typeof window !== 'undefined';
+    }
+    catch {
+        return false;
+    }
+}
+function isValidMessage(event, sourceEnv, currentEnv) {
+    return (event.source !== currentEnv &&
+        event.source === sourceEnv &&
+        event.data &&
+        event.data.constructor.name === 'Uint8Array');
+}
+export function createIframeProvider({ iframe, url, logger }) {
+    iframe.src = url;
+    let disposed = false;
+    let iframePromise = null;
+    const subscribers = new Set();
+    function waitForIframe(callback) {
+        if (iframe.contentWindow) {
+            return callback(iframe.contentWindow);
+        }
+        if (iframePromise) {
+            iframePromise.then(callback);
+            return;
+        }
+        iframePromise = new Promise(resolve => {
+            iframe.addEventListener('load', () => {
+                resolve(iframe.contentWindow ?? null);
+                callback(iframe.contentWindow ?? null);
+                iframePromise = null;
+            }, { once: true });
+        });
+    }
+    const messageHandler = (event) => {
+        if (disposed)
+            return;
+        waitForIframe(iframe => {
+            if (disposed)
+                return;
+            if (!iframe)
+                return;
+            if (!isValidMessage(event, iframe, window))
+                return;
+            for (const subscriber of subscribers) {
+                subscriber(event.data);
+            }
+        });
+    };
+    if (hasWindow()) {
+        window.addEventListener('message', messageHandler);
+    }
+    return {
+        logger: logger ?? createDefaultLogger(),
+        isCorrectEnvironment() {
+            return hasWindow();
+        },
+        postMessage(message) {
+            if (disposed)
+                return;
+            waitForIframe(iframe => {
+                if (!iframe)
+                    return;
+                if (disposed)
+                    return;
+                iframe.postMessage(message, '*', [message.buffer]);
+            });
+        },
+        subscribe(callback) {
+            subscribers.add(callback);
+            return () => {
+                subscribers.delete(callback);
+            };
+        },
+        dispose() {
+            disposed = true;
+            iframe.src = '';
+            iframePromise = null;
+            subscribers.clear();
+            if (hasWindow()) {
+                window.removeEventListener('message', messageHandler);
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createIframeProvider } from './createIframeProvider';
+export { createContainer } from './createContainer';
+export type { Container } from './createContainer';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createIframeProvider } from './createIframeProvider';
+export { createContainer } from './createContainer';

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@novasamatech/host-container",
+  "type": "module",
+  "version": "0.4.0",
+  "description": "Host container for hosting and managing products within the Polkadot ecosystem.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/novasamatech/spektr-sdk.git"
+  },
+  "keywords": [
+    "polkadot",
+    "spektr",
+    "dapp"
+  ],
+  "main": "dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@polkadot-api/json-rpc-provider": "0.0.4",
+    "@novasamatech/host-api": "0.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}