@icp-sdk/signer 5.2.0

package/lib/esm/web/postMessageTransport.js

@@ -0,0 +1,113 @@
+import { HeartbeatClient } from './heartbeat/client.js';
+import { PostMessageChannel } from './postMessageChannel.js';
+const NON_CLICK_ESTABLISHMENT_LINK = 'https://github.com/slide-computer/signer-js/blob/main/packages/signer-web/README.md#channels-must-be-established-in-a-click-handler';
+/** Error thrown by {@link PostMessageTransport} for transport-level failures. */
+export class PostMessageTransportError extends Error {
+}
+// Tracks whether we're inside a click event handler.
+// Capture phase sets true, bubble phase resets to false.
+let withinClick = false;
+if (globalThis.window) {
+    globalThis.window.addEventListener('click', () => (withinClick = true), true);
+    globalThis.window.addEventListener('click', () => (withinClick = false));
+}
+/**
+ * ICRC-29 post message transport for communicating with web-based signers.
+ *
+ * Opens a window to the signer's URL and establishes a communication channel
+ * using the ICRC-29 heartbeat protocol (`icrc29_status` polling). Messages
+ * are exchanged via `window.postMessage`.
+ * @see https://github.com/dfinity/wg-identity-authentication/blob/main/topics/icrc_29_window_post_message_transport.md
+ * @example
+ * ```ts
+ * const transport = new PostMessageTransport({ url: "https://oisy.com/sign" });
+ * const signer = new Signer({ transport });
+ * ```
+ */
+export class PostMessageTransport {
+    #options;
+    constructor(options) {
+        const isSecureContext = (() => {
+            try {
+                const url = new URL(options.url);
+                return (url.protocol === 'https:' ||
+                    url.hostname === '127.0.0.1' ||
+                    url.hostname.split('.').slice(-1)[0] === 'localhost');
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (!isSecureContext) {
+            throw new PostMessageTransportError('Invalid signer RPC url');
+        }
+        this.#options = {
+            windowOpenerFeatures: '',
+            window: globalThis.window,
+            establishTimeout: 120000,
+            pendingTimeout: 300000,
+            disconnectTimeout: 2000,
+            statusPollingRate: 300,
+            crypto: globalThis.crypto,
+            manageFocus: true,
+            closeOnEstablishTimeout: true,
+            closeOnPendingTimeout: true,
+            detectNonClickEstablishment: true,
+            ...options,
+        };
+    }
+    /**
+     * Opens the signer window and establishes a communication channel
+     * via the ICRC-29 heartbeat handshake.
+     * @throws {PostMessageTransportError} If called outside a click handler
+     *   (when `detectNonClickEstablishment` is enabled), if the window
+     *   cannot be opened, or if the handshake times out.
+     */
+    establishChannel() {
+        if (this.#options.detectNonClickEstablishment && !withinClick) {
+            return Promise.reject(new PostMessageTransportError(`Signer window should not be opened outside of click handler, see: ${NON_CLICK_ESTABLISHMENT_LINK}`));
+        }
+        let signerWindow;
+        try {
+            const result = this.#options.window.open(this.#options.url, `${new URL(this.#options.url).origin}-signer-window`, this.#options.windowOpenerFeatures);
+            if (!result) {
+                return Promise.reject(new PostMessageTransportError('Signer window could not be opened'));
+            }
+            signerWindow = result;
+        }
+        catch (error) {
+            return Promise.reject(new PostMessageTransportError(error instanceof Error ? error.message : 'Signer window could not be opened'));
+        }
+        return new Promise((resolve, reject) => {
+            let channel;
+            new HeartbeatClient({
+                ...this.#options,
+                signerWindow,
+                onEstablish: (origin, status) => {
+                    channel = new PostMessageChannel({
+                        ...this.#options,
+                        signerOrigin: origin,
+                        signerWindow,
+                        signerStatus: status,
+                    });
+                    resolve(channel);
+                },
+                onEstablishTimeout: () => {
+                    if (this.#options.closeOnEstablishTimeout) {
+                        signerWindow.close();
+                    }
+                    reject(new PostMessageTransportError('Communication channel could not be established within a reasonable time'));
+                },
+                onPendingTimeout: () => {
+                    if (this.#options.closeOnPendingTimeout) {
+                        signerWindow.close();
+                    }
+                    reject(new PostMessageTransportError('Communication channel was pending for too long'));
+                },
+                onDisconnect: () => channel.close(),
+                onStatusChange: status => channel.changeStatus(status),
+            });
+        });
+    }
+}
+//# sourceMappingURL=postMessageTransport.js.map

package/lib/esm/web/postMessageTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postMessageTransport.js","sourceRoot":"","sources":["../../../src/web/postMessageTransport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "@icp-sdk/signer",
+  "version": "5.2.0",
+  "author": "DFINITY Stiftung <sdk@dfinity.org>",
+  "license": "Apache-2.0",
+  "description": "Library to interact with signers on the Internet Computer",
+  "homepage": "https://js.icp.build/signer/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dfinity/icp-js-signer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dfinity/icp-js-signer/issues"
+  },
+  "keywords": [
+    "internet computer",
+    "internet-computer",
+    "ic",
+    "dfinity",
+    "signer",
+    "wallet",
+    "actor",
+    "dfx",
+    "canister",
+    "candid",
+    "motoko",
+    "javascript",
+    "typescript",
+    "blockchain",
+    "crypto",
+    "distributed",
+    "api",
+    "sdk"
+  ],
+  "type": "module",
+  "types": "./lib/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/esm/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "default": "./lib/esm/index.js"
+    },
+    "./agent": {
+      "types": "./lib/esm/agent/index.d.ts",
+      "import": "./lib/esm/agent/index.js",
+      "default": "./lib/esm/agent/index.js"
+    },
+    "./web": {
+      "types": "./lib/esm/web/index.d.ts",
+      "import": "./lib/esm/web/index.js",
+      "default": "./lib/esm/web/index.js"
+    },
+    "./extension": {
+      "types": "./lib/esm/extension/index.d.ts",
+      "import": "./lib/esm/extension/index.js",
+      "default": "./lib/esm/extension/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json && npm run lint:package",
+    "test": "vitest run",
+    "test:e2e": "npm run build && npm run build:e2e && playwright test",
+    "build:e2e": "cd e2e/fixtures && esbuild relying-party.ts mock-wallet.ts mock-auth-provider.ts --bundle --format=iife --outdir=. --out-extension:.js=.bundle.js --alias:@icp-sdk/signer=../../lib/esm/index.js --alias:@icp-sdk/signer/web=../../lib/esm/web/index.js --alias:@icp-sdk/signer/extension=../../lib/esm/extension/index.js --alias:@icp-sdk/signer/agent=../../lib/esm/agent/index.js",
+    "lint": "eslint src/",
+    "lint:fix": "eslint --fix src/",
+    "lint:package": "publint --strict",
+    "attw": "attw --pack .",
+    "docs": "cd docs && npm run build",
+    "size": "size-limit --json",
+    "prettier:check": "npx -p prettier -p pretty-quick pretty-quick --check --branch main",
+    "prettier:format": "npx -p prettier -p pretty-quick pretty-quick --branch main",
+    "prepare": "husky"
+  },
+  "peerDependencies": {
+    "@icp-sdk/core": "^5"
+  },
+  "size-limit": [
+    {
+      "name": "@icp-sdk/signer",
+      "path": "./lib/esm/index.js",
+      "limit": "15 kb"
+    },
+    {
+      "name": "@icp-sdk/signer/agent",
+      "path": "./lib/esm/agent/index.js",
+      "limit": "15 kb"
+    },
+    {
+      "name": "@icp-sdk/signer/web",
+      "path": "./lib/esm/web/index.js",
+      "limit": "15 kb"
+    },
+    {
+      "name": "@icp-sdk/signer/extension",
+      "path": "./lib/esm/extension/index.js",
+      "limit": "15 kb"
+    }
+  ],
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.58.2",
+    "@size-limit/esbuild": "^12.0.1",
+    "@size-limit/preset-small-lib": "^12.0.1",
+    "@tsconfig/node22": "^22.0.5",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "esbuild": "^0.27.4",
+    "eslint": "^10.1.0",
+    "eslint-plugin-jsdoc": "^62.8.1",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.8.1",
+    "pretty-quick": "^4.2.2",
+    "publint": "^0.3.18",
+    "serve": "^14.2.6",
+    "size-limit": "^12.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.1"
+  }
+}