windkit 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.2.3] - 2026-03-02
+
+Published: 2026-03-02T14:07:04Z
+
+### Changed
+
+- Session storage key standardized to `"vex-session"`.
+- Login identity payload compacted with standardized keys:
+  - `pi` (peer id)
+  - `na` (app name)
+  - `ic` (icon)
+  - `do` (origin)
+  - optional `auth` (cached identity proof)
+- RPC method names standardized:
+  - `signRequest`
+  - `signMessage`
+  - `sharedSecret`
+
+### Added
+
+- `clearSession()` helper for manual session reset.
+- Smart session reuse:
+  - Reuses stored `peerID`
+  - Reuses permission hints (`account@permission`) when available.
+
+### Fixed
+
+- Hardened session loader:
+  - Automatically clears expired or malformed session payloads.
+- Improved disconnect cleanup:
+  - Safe destroy/disconnect (best-effort, non-throwing).
+
+### Improved
+
+- Optimized for low-memory environments:
+  - Lightweight heartbeat with jitter
+  - Reduced message routing allocations
+  - Lower background CPU usage on mobile devices
+
+---
+
+## [0.2.1] - 2025-10-13
+
+Published: 2025-10-13T16:28:38Z
+
+### Added
+
+- PeerJS signaling support.
+- Session persistence via `sessionStorage`.
+- Transaction signing via Vexanium Signing Request (VSR).
+- Message signing support.
+- Shared secret derivation (ECDH).
+
+---
+
+## [0.2.0] - 2025-10-06
+
+Published: 2025-10-06T14:44:23Z
+
+### Added
+
+- Structured WebRTC connection lifecycle.
+- WalletSession abstraction layer.
+- Basic login flow via embedded PeerID inside VSR.
+- Request/response routing via internal request IDs.
+
+### Improved
+
+- More predictable session initialization flow.
+- Internal protocol normalization groundwork.
+
+---
+
+## [0.1.1] - 2025-08-12
+
+Published: 2025-08-12T01:33:25Z
+
+### Added
+
+- Initial public release of WindKit.
+- Basic VSR identity login.
+- WebRTC DataConnection integration.
+- Minimal transaction signing flow.

package/README.md

@@ -2,82 +2,301 @@
 
 [![npm version](https://img.shields.io/npm/v/windkit.svg)](https://www.npmjs.com/package/windkit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-A protocol to connect Vexanium DApps to the Wind wallet.
 
-## Features
+WindKit is a lightweight WebRTC protocol for connecting Vexanium DApps to Wind Wallet using PeerJS and WharfKit Signing Requests (VSR).
+
+It enables secure cross-device login and transaction signing without requiring browser extensions.
+
+Designed for production environments, including low-RAM mobile devices.
+
+---
+
+## ✨ Features
+
 - Cross-device login via VSR (Vexanium Signing Request)
-- Transaction signing (single or multiple actions)
+- Transaction signing (single action, multiple actions, or full transaction)
+- Optional broadcast control (sign-only or broadcast)
 - Message signing
-- Shared secret (ECDH) for encryption
+- Shared secret derivation (ECDH)
+- Session persistence via `sessionStorage`
+- Low-memory heartbeat strategy
+- Pure ESM module (JavaScript-only)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install windkit
+```
+
+WindKit is **ESM-only**.
+
+Your project must include:
+
+```json
+{
+  "type": "module"
+}
+```
 
-## Initialize the Connector
-```javascript
+---
+
+## 🚀 Quick Start
+
+### Create Connector
+
+```js
 import { WindConnector } from "windkit";
 
 const connector = new WindConnector();
-connector.on("session", onSession); // fires after wallet approves login
+
+connector.on("session", (session, proof) => {
+  console.log("Connected as:", session.permissionLevel?.toString());
+});
+
 await connector.connect();
 ```
 
-## Create a Login Request and Open the Wallet
-```javascript
-// Build a VSR and deep-link / QR it to the wallet
-const vsr = connector.createLoginRequest("Vexanium DApp", "https://example.com/icon.png");
-const request = vsr.split(":")[1];
+By default, WindKit uses PeerJS default signaling.
+
+---
+
+## 🌐 Custom PeerJS Server (Optional)
 
-// Open Wind Wallet login (adjust the URL/host as needed)
-const walletUrl = `https://windwallet.app/login?vsr=${request}`;
-window.open(walletUrl, "Wind Wallet");
+```js
+connector.setServer("peer.yourdomain.com", 443, "/", true);
 ```
 
-## Receive a WalletSession
-```javascript
-import { ABICache } from "@wharfkit/abicache";
+Signature:
 
-const abiCache = new ABICache({/* optional custom fetch */});
+```js
+setServer(host, port, path, secure);
+```
 
-function onSession(session, proof) {
-  // Optional on first login: verify IdentityProof as needed
-  const account = proof?.signer?.toString?.(); // e.g., "userxyz@active"
+Add custom ICE server:
 
-  session.setABICache(abiCache);  // faster ABI (de)serialization
-  session.onClose(() => console.log("Disconnected from wallet"));
-  
-  // Store for later use
-  Store.session = session;
-}
+```js
+connector.addIceServer({
+  urls: "stun:stun.cloudflare.com:3478"
+});
 ```
 
-## Send a Transaction
-```javascript
+---
+
+## 🔐 Login Flow (VSR)
+
+```js
+const vsr = connector.createLoginRequest(
+  "My Vexanium DApp",
+  "https://example.com/icon.png"
+);
+
+const payload = vsr.startsWith("vsr:") ? vsr.slice(4) : vsr;
+
+window.open(
+  `https://wallet.windcrypto.com/login?vsr=${encodeURIComponent(payload)}`,
+  "Wind Wallet"
+);
+```
+
+Wallet flow:
+
+1. Decode VSR  
+2. Connect to embedded PeerID  
+3. Send `LOGIN_OK`  
+4. Emit session  
+
+---
+
+## 🔄 Session Handling
+
+```js
+connector.on("session", (session, proof) => {
+  session.onClose(() => {
+    console.log("Wallet disconnected");
+  });
+
+  session.onError((error) => {
+    console.error("Session error:", error);
+  });
+
+  window.appSession = session;
+});
+```
+
+---
+
+## ✍️ Send Transaction
+
+### With ABI Cache (Recommended)
+
+```js
 import { Action } from "@wharfkit/antelope";
+import { ABICache } from "@wharfkit/abicache";
+
+const abiCache = new ABICache();
+appSession.setABICache(abiCache);
 
-// Example: transfer VEX
 const abi = await abiCache.getAbi("vex.token");
-const data = {
-  from: "aiueo",
-  to: "babibu",
-  quantity: "1.0000 VEX",
-  memo: "test transfer"
-};
 
 const action = Action.from(
   {
     account: "vex.token",
     name: "transfer",
-    data,
-    authorization: [Store.session.permissionLevel]
+    data: {
+      from: "alice",
+      to: "bob",
+      quantity: "1.0000 VEX",
+      memo: "WindKit test"
+    },
+    authorization: [appSession.permissionLevel]
   },
   abi
 );
 
-// By default, transact() broadcasts. Set { broadcast: false } to sign only.
-const result = await Store.session.transact({ action });
-// result is either SendTransactionResponse (broadcast) or SignedTransaction (sign-only)
+const result = await appSession.transact({ action });
+
 console.log(result.transaction_id ?? result.id);
 ```
 
-> Notes  
-> - Class names: `WindConnector` (connector) and `WalletSession` (active session).  
-> - Chain ID is handled internally by `WalletSession.ChainID` (Vexanium mainnet).  
-> - For re-login, the `session` event may be called without `proof` (use `session.permissionLevel`).  
+---
+
+### Sign Only (No Broadcast)
+
+```js
+await appSession.transact(
+  { action },
+  { broadcast: false }
+);
+```
+
+---
+
+## 📝 Sign Message
+
+```js
+const signature = await appSession.signMessage("Hello Wind!");
+console.log(signature.toString());
+```
+
+---
+
+## 🔑 Shared Secret (ECDH)
+
+```js
+import { PublicKey } from "@wharfkit/antelope";
+
+const pub = PublicKey.from("PUB_K1_...");
+const secret = await appSession.sharedSecret(pub);
+
+console.log(secret.toString());
+```
+
+---
+
+## 💾 Session Storage
+
+WindKit stores session data in:
+
+```js
+sessionStorage["vex-session"]
+```
+
+Example structure:
+
+```json
+{
+  "peerID": "VEX-xxxx",
+  "permission": "account@active",
+  "expiration": "2026-03-01T12:00:00",
+  "auth": "base64u_identity_proof"
+}
+```
+
+Clear session manually:
+
+```js
+import { clearSession } from "windkit";
+
+clearSession();
+```
+
+---
+
+## 🏗 Architecture
+
+### WindConnector
+
+- Creates VSR identity login
+- Hosts PeerJS PeerID (DApp-side)
+- Waits for wallet connection
+- Emits session
+
+### WalletSession
+
+- Sends:
+  - `signRequest`
+  - `signMessage`
+  - `sharedSecret`
+- Routes replies via request IDs
+- Lightweight heartbeat ping
+- Handles account change events
+
+---
+
+## 🔎 Protocol Notes
+
+Transaction signing method:
+
+```
+signRequest
+```
+
+Wallet push events handled:
+
+```
+LOGIN_OK
+ACTIVE_ACCOUNT_CHANGED
+```
+
+All communication occurs over PeerJS `DataConnection`.
+
+---
+
+## ⚙ Technical Details
+
+Chain ID is internally fixed via:
+
+```js
+WalletSession.ChainID
+```
+
+Dependencies:
+
+- `@wharfkit/signing-request`
+- `@wharfkit/antelope`
+- `peerjs`
+- `pako`
+
+Optimized for:
+
+- Low-RAM mobile devices
+- Background browser tabs
+- Unstable WebRTC networks
+
+---
+
+## 🔐 Security Model
+
+- IdentityProof can be verified by the DApp (recommended).
+- Private keys never leave the wallet.
+- VSR ensures transaction integrity.
+- PeerID is embedded inside the VSR payload to prevent misrouting.
+
+---
+
+## 📄 License
+
+MIT License  
+© Wind Stack

package/index.js

@@ -0,0 +1,3 @@
+export { WindConnector } from "./src/WindConnector.js";
+export { WalletSession } from "./src/WalletSession.js";
+export { saveSession, loadSession, clearSession } from "./src/StoreSession.js";

package/package.json

@@ -1,61 +1,59 @@
 {
   "name": "windkit",
-  "version": "0.2.1",
-  "description": "A protocol for connecting Vexanium DApps to the Wind wallet, enabling secure communication and transaction signing.",
+  "version": "0.2.3",
+  "description": "Lightweight protocol to connect Vexanium DApps to Wind Wallet via PeerJS and VSR.",
+  "license": "MIT",
+  "author": "windstack",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/**",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/windvex/windkit.git"
   },
+  "bugs": {
+    "url": "https://github.com/windvex/windkit/issues"
+  },
+  "homepage": "https://github.com/windvex/windkit#readme",
   "keywords": [
-    "cryptocurrency",
-    "web3",
-    "dapp",
-    "walletconnect",
-    "windkit",
-    "web-rtc",
-    "peerjs",
     "vexanium",
     "vex",
+    "wind",
+    "wallet",
+    "web3",
+    "peerjs",
+    "webrtc",
+    "wharfkit",
+    "signing-request",
+    "vsr",
     "blockchain"
   ],
-  "license": "MIT",
-  "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.cjs"
-      }
-    }
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
   "scripts": {
-    "build": "tsup",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build",
-    "test": "echo \"(no tests yet)\""
+    "test": "node -e \"console.log('windkit ok')\"",
+    "pack:check": "npm pack --dry-run",
+    "publish:npm": "npm run pack:check && npm publish --access public"
   },
   "dependencies": {
     "@wharfkit/abicache": "^1.2.2",
-    "@wharfkit/antelope": "^1.0.13",
+    "@wharfkit/antelope": "^1.1.1",
     "@wharfkit/signing-request": "^3.2.0",
     "pako": "^2.1.0",
-    "peerjs": "^1.5.4"
+    "peerjs": "^1.5.5"
   },
-  "devDependencies": {
-    "@types/pako": "^2.0.4",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3"
+  "engines": {
+    "node": ">=18"
   }
-}
+}

package/src/StoreSession.js

@@ -0,0 +1,103 @@
+// windkit/StoreSession.js
+// Ultra Clean++ (single replace)
+// ✅ sessionStorage SSOT for pairing
+// ✅ auto-clear invalid/expired
+// ✅ safe storage guards (private mode / SSR)
+
+import { TimePointSec } from "@wharfkit/antelope";
+
+const KEY = "vex-session";
+
+function hasSessionStorage() {
+  try {
+    return typeof sessionStorage !== "undefined" && sessionStorage != null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @typedef {Object} StoredSession
+ * @property {string} peerID
+ * @property {string} permission           // "account@active"
+ * @property {string|TimePointSec} expiration
+ * @property {string} auth                 // Base64u IdentityProof payload
+ */
+
+export function saveSession(data) {
+  if (!hasSessionStorage()) return;
+
+  const exp =
+    typeof data?.expiration === "string"
+      ? data.expiration
+      : data?.expiration?.toString?.() ?? String(data?.expiration ?? "");
+
+  const payload = {
+    peerID: String(data?.peerID || ""),
+    permission: String(data?.permission || ""),
+    expiration: String(exp || ""),
+    auth: String(data?.auth || ""),
+  };
+
+  try {
+    sessionStorage.setItem(KEY, JSON.stringify(payload));
+  } catch {
+    // ignore (quota/private mode)
+  }
+}
+
+export function clearSession() {
+  if (!hasSessionStorage()) return;
+  try {
+    sessionStorage.removeItem(KEY);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Load session from sessionStorage (auto-clears if invalid/expired).
+ * @returns {null | {peerID:string, permission:string, expiration:TimePointSec, auth:string}}
+ */
+export function loadSession() {
+  if (!hasSessionStorage()) return null;
+
+  let raw = "";
+  try {
+    raw = sessionStorage.getItem(KEY) || "";
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object") {
+      clearSession();
+      return null;
+    }
+
+    const peerID = String(data.peerID || "");
+    const permission = String(data.permission || "");
+    const auth = String(data.auth || "");
+    const expRaw = String(data.expiration || "");
+
+    if (!peerID || !permission || !auth || !expRaw) {
+      clearSession();
+      return null;
+    }
+
+    const expiration = TimePointSec.fromString(expRaw);
+    const expMs = expiration.toDate().getTime();
+
+    if (!Number.isFinite(expMs) || expMs <= Date.now()) {
+      clearSession();
+      return null;
+    }
+
+    return { peerID, permission, expiration, auth };
+  } catch {
+    clearSession();
+    return null;
+  }
+}