windkit 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows Semantic Versioning.
+
+---
+
+## [0.2.2] - 2026-03-02
+
+### Changed
+
+- Session storage key standardized to `"vex-session"`.
+- Login identity request now stores compact app info keys:
+  - `pi` (peer id), `na` (app name), `ic` (icon), `do` (origin), optional `auth` (cached proof).
+- Request method names standardized:
+  - `signRequest`, `signMessage`, `sharedSecret`.
+
+### Added
+
+- `clearSession()` helper.
+- Session reuse:
+  - Reuses saved `peerID` and hints (`account@permission`) when present.
+
+### Fixed
+
+- Safer session loading (auto-clears invalid or expired payloads).
+- Improved cleanup on disconnect (best-effort destroy/disconnect).
+
+### Improved
+
+- Low-memory friendly behavior:
+  - Lightweight heartbeat/ping with jitter (best-effort).
+  - Minimal allocations on message routing.
+
+---
+
+## [0.2.1]
+
+### Added
+
+- Initial PeerJS signaling support.
+- Session persistence via sessionStorage.
+- Transaction signing via VSR.
+- Message signing.
+- Shared secret (ECDH).
+
+---
+
+## [0.1.1]
+
+### Added
+
+- Initial public release of WindKit.

package/README.md

@@ -2,82 +2,257 @@
 
 [![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.
+
+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.
+
+---
 
 ## 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 (sign-only or broadcast)
 - Message signing
-- Shared secret (ECDH) for encryption
+- Shared secret derivation (ECDH)
+- Session persistence via sessionStorage
+- Lightweight keepalive (low memory footprint)
+- Pure ESM module
+
+---
+
+## Installation
+
+npm install windkit
+
+WindKit is ESM-only.
+
+Your project must use:
+
+{
+  "type": "module"
+}
+
+---
+
+## Quick Start
+
+### Create Connector
 
-## Initialize the Connector
-```javascript
 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 relies on PeerJS default signaling behavior (no host/port/path/secure configured).
 
-// Open Wind Wallet login (adjust the URL/host as needed)
-const walletUrl = `https://windwallet.app/login?vsr=${request}`;
-window.open(walletUrl, "Wind Wallet");
-```
+---
 
-## Receive a WalletSession
-```javascript
-import { ABICache } from "@wharfkit/abicache";
+### Use Your Own PeerJS Server (Optional)
 
-const abiCache = new ABICache({/* optional custom fetch */});
+connector.setServer("peer.yourdomain.com", 443, "/", true);
 
-function onSession(session, proof) {
-  // Optional on first login: verify IdentityProof as needed
-  const account = proof?.signer?.toString?.(); // e.g., "userxyz@active"
+Signature:
 
-  session.setABICache(abiCache);  // faster ABI (de)serialization
-  session.onClose(() => console.log("Disconnected from wallet"));
-  
-  // Store for later use
-  Store.session = session;
-}
-```
+setServer(host, port, path, secure)
+
+Add custom STUN/TURN server:
+
+connector.addIceServer({
+  urls: "stun:stun.cloudflare.com:3478"
+});
+
+---
+
+## Login Flow (VSR)
+
+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
+
+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)
 
-## Send a Transaction
-```javascript
 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: "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)
+
+await appSession.transact(
+  { action },
+  { broadcast: false }
+);
+
+---
+
+## Sign Message
+
+const signature = await appSession.signMessage("Hello Wind!");
+console.log(signature.toString());
+
+---
+
+## Shared Secret (ECDH)
+
+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:
+
+sessionStorage["vex-session"]
+
+Example structure:
+
+{
+  "peerID": "VEX-xxxx",
+  "permission": "account@active",
+  "expiration": "2026-03-01T12:00:00",
+  "auth": "base64u_identity_proof"
+}
+
+To clear session manually:
+
+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 keepalive ping
+- Handles account change events
+
+---
+
+## Protocol Notes
+
+Transaction signing method name:
+"signRequest"
+
+Wallet push events handled:
+LOGIN_OK
+ACTIVE_ACCOUNT_CHANGED
+
+All communication occurs via PeerJS DataConnection.
+
+---
+
+## Technical Details
+
+Chain ID is fixed internally via:
+WalletSession.ChainID
+
+Uses:
+- @wharfkit/signing-request
+- @wharfkit/antelope
+- peerjs
+- pako (zlib compression)
+
+Designed for:
+- Low-RAM mobile devices
+- Background tabs
+- Unstable WebRTC environments
+
+---
+
+## Security Model
+
+- IdentityProof can be verified by the DApp (recommended).
+- Private keys never leave the wallet.
+- VSR ensures transaction integrity.
+- PeerID is embedded inside VSR 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.0",
-  "description": "A protocol for connecting Vexanium DApps to the Wind wallet, enabling secure communication and transaction signing.",
+  "version": "0.2.2",
+  "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;
+  }
+}