windkit 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0
+
+- Added Wind Wallet in-app browser injected provider support.
+- Added `InjectedWalletSession`.
+- Added `WindClient` hybrid connector.
+- Added `connectWindWallet()` helper.
+- Keeps existing QR/VSR + PeerJS flow as fallback.
+- Exposes provider detection helpers: `getInjectedWindProvider()` and `isWindWalletInjected()`.
+
+
 All notable changes to this project are documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).

package/README.md

@@ -24,6 +24,85 @@ Designed for production environments, including low-RAM mobile devices.
 
 ---
 
+## 🧩 In-App Browser Injected Provider
+
+WindKit now supports Wind Wallet's in-app DApp Browser provider, similar to MetaMask / Phantom / Rabby.
+
+When a DApp is opened inside Wind Wallet Browser, Wind Wallet injects:
+
+```js
+window.wind
+window.windwallet
+window.windWallet
+window.vexanium
+window.vex
+```
+
+Use the hybrid client to support both injected provider and QR/VSR fallback:
+
+```js
+import { WindClient } from "windkit";
+
+const wind = new WindClient();
+
+const session = await wind.connect({
+  name: "My Vexanium DApp",
+  icon: "https://example.com/icon.png",
+
+  // Called only when the DApp is opened outside Wind Wallet Browser.
+  // Render this VSR as QR, or show your existing login modal.
+  onLoginRequest(vsr) {
+    console.log("Show QR:", vsr);
+  }
+});
+
+console.log("Connected:", session.permissionLevel?.toString());
+```
+
+### Direct injected request
+
+```js
+import { InjectedWalletSession } from "windkit";
+
+if (InjectedWalletSession.isAvailable()) {
+  const session = await InjectedWalletSession.connect();
+
+  await session.signMessage("Hello Wind!");
+}
+```
+
+### Provider API
+
+Inside Wind Wallet Browser, DApps can also call the provider directly:
+
+```js
+const accounts = await window.wind.request({
+  method: "vex_requestAccounts"
+});
+
+const signature = await window.wind.request({
+  method: "vex_signMessage",
+  params: ["Hello Wind!"]
+});
+
+const result = await window.wind.request({
+  method: "signRequest",
+  params: ["vsr:..."]
+});
+```
+
+### Recommended DApp logic
+
+```txt
+1. Try injected provider first: window.wind / window.vexanium.
+2. If not available, use QR/VSR + PeerJS fallback.
+3. Keep signing approval inside Wind Wallet.
+```
+
+This keeps old QR pairing working while enabling MetaMask-style connect inside the Wind Wallet app.
+
+---
+
 ## 📦 Installation
 
 ```bash

package/index.js

@@ -1,3 +1,11 @@
 export { WindConnector } from "./src/WindConnector.js";
 export { WalletSession } from "./src/WalletSession.js";
-export { saveSession, loadSession, clearSession } from "./src/StoreSession.js";
+export {
+  InjectedWalletSession,
+  WindClient,
+  connectWindWallet,
+  getInjectedWindProvider,
+  isWindWalletInjected,
+  requestWithTimeout,
+} from "./src/InjectedWindProvider.js";
+export { saveSession, loadSession, clearSession } from "./src/StoreSession.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "windkit",
-  "version": "0.2.3",
-  "description": "Lightweight protocol to connect Vexanium DApps to Wind Wallet via PeerJS and VSR.",
+  "version": "0.3.0",
+  "description": "Hybrid protocol to connect Vexanium DApps to Wind Wallet using injected provider, PeerJS, and VSR.",
   "license": "MIT",
   "author": "windstack",
   "type": "module",
@@ -35,7 +35,11 @@
     "wharfkit",
     "signing-request",
     "vsr",
-    "blockchain"
+    "blockchain",
+    "injected-provider",
+    "in-app-browser",
+    "metamask-compatible",
+    "phantom-compatible"
   ],
   "sideEffects": false,
   "publishConfig": {
@@ -56,4 +60,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/src/InjectedWindProvider.js

@@ -0,0 +1,518 @@
+// windkit/InjectedWindProvider.js
+// WindKit injected-provider bridge
+// ✅ In-app browser first (window.wind / window.windwallet / window.vexanium)
+// ✅ Keeps QR/VSR + PeerJS fallback untouched
+// ✅ MetaMask-style request({ method, params }) API for Wind Wallet browser
+// ✅ No wallet keys, no signing logic here — DApp-side transport only
+
+import { SigningRequest } from "@wharfkit/signing-request";
+import {
+  Checksum512,
+  Name,
+  PermissionLevel,
+  PublicKey,
+  Signature,
+  SignedTransaction,
+} from "@wharfkit/antelope";
+import zlib from "pako";
+
+import { WindConnector } from "./WindConnector.js";
+
+const DEFAULT_TIMEOUT_MS = 90_000;
+
+function normalizeTimeoutMs(v, fallback = DEFAULT_TIMEOUT_MS) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(1000, Math.trunc(n));
+}
+
+function setTimer(fn, ms) {
+  try {
+    return globalThis.setTimeout(fn, ms);
+  } catch {
+    return setTimeout(fn, ms);
+  }
+}
+
+function clearTimer(id) {
+  try {
+    globalThis.clearTimeout(id);
+  } catch {
+    clearTimeout(id);
+  }
+}
+
+function getWindowLike() {
+  try {
+    if (typeof globalThis !== "undefined") return globalThis;
+  } catch {}
+  return undefined;
+}
+
+function normalizeParams(params) {
+  if (params === undefined) return [];
+  return Array.isArray(params) ? params : [params];
+}
+
+function replyError(reply, fallback) {
+  const err = reply?.error;
+  if (typeof err === "string") return new Error(err);
+  if (err?.message) return new Error(err.message);
+  if (reply?.message) return new Error(reply.message);
+  return new Error(fallback || "Wind Wallet request failed.");
+}
+
+function parseAccountLike(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return parseAccountLike(value[0]);
+  if (typeof value === "object") {
+    return (
+      value.permission ||
+      value.permissionLevel ||
+      value.account ||
+      value.address ||
+      value.actor ||
+      ""
+    );
+  }
+  return "";
+}
+
+function toPermissionLevel(value) {
+  const raw = parseAccountLike(value);
+  if (!raw) return undefined;
+
+  // Vexanium permission is canonical actor@permission.
+  if (String(raw).includes("@")) {
+    return PermissionLevel.from(String(raw));
+  }
+
+  // Some injected providers may return { actor, permission } separately.
+  if (value && typeof value === "object" && value.actor && value.permission) {
+    return PermissionLevel.from(`${value.actor}@${value.permission}`);
+  }
+
+  return undefined;
+}
+
+function isRequestProvider(value) {
+  return Boolean(value && typeof value.request === "function");
+}
+
+/**
+ * Return the first Wind-compatible injected provider available in the current browser.
+ *
+ * Wind Wallet app injects several aliases for compatibility:
+ * - window.wind
+ * - window.windwallet
+ * - window.windWallet
+ * - window.vexanium
+ * - window.vex
+ */
+export function getInjectedWindProvider(scope) {
+  const w = scope || getWindowLike();
+  if (!w) return null;
+
+  const candidates = [
+    w.wind,
+    w.windwallet,
+    w.windWallet,
+    w.vexanium,
+    w.vex,
+  ];
+
+  for (const provider of candidates) {
+    if (isRequestProvider(provider)) return provider;
+  }
+
+  return null;
+}
+
+export function isWindWalletInjected(scope) {
+  const provider = getInjectedWindProvider(scope);
+  return Boolean(provider?.isWindWallet || provider?.isWind || provider?.request);
+}
+
+/**
+ * InjectedWalletSession
+ * DApp-side session object for Wind Wallet in-app browser.
+ *
+ * It intentionally mirrors WalletSession's public API:
+ * - transact()
+ * - signRequest()
+ * - signMessage()
+ * - sharedSecret()
+ * - permissionLevel
+ */
+export class InjectedWalletSession {
+  static ChainID = "f9f432b1851b5c179d2091a96f593aaed50ec7466b74f89301f957a83e56ce1f";
+
+  /** @type {any} */
+  #provider;
+
+  /** @type {{zlib:any, abiProvider?:any} | undefined} */
+  #encodingOptions;
+
+  /** @type {PermissionLevel | undefined} */
+  #permissionLevel;
+
+  /** @type {(permission: PermissionLevel) => void | undefined} */
+  #accountChangeListener;
+
+  /** @type {() => void | undefined} */
+  #closeListener;
+
+  /** @type {(error: Error) => void | undefined} */
+  #errorListener;
+
+  constructor(provider, permissionLevel) {
+    if (!isRequestProvider(provider)) {
+      throw new Error("Wind Wallet injected provider was not found.");
+    }
+
+    this.#provider = provider;
+
+    const perm = toPermissionLevel(permissionLevel);
+    if (perm) this.#permissionLevel = perm;
+
+    this.#bindProviderEvents();
+  }
+
+  static isAvailable(scope) {
+    return isWindWalletInjected(scope);
+  }
+
+  static getProvider(scope) {
+    return getInjectedWindProvider(scope);
+  }
+
+  /**
+   * Request accounts from the injected Wind Wallet provider.
+   * @param {{provider?: any, timeoutMs?: number}=} options
+   */
+  static async connect(options = {}) {
+    const provider = options.provider || getInjectedWindProvider();
+    if (!provider) throw new Error("Wind Wallet injected provider is not available.");
+
+    const result = await requestWithTimeout(
+      provider,
+      "vex_requestAccounts",
+      [],
+      options.timeoutMs
+    );
+
+    const permission = toPermissionLevel(result) || toPermissionLevel(result?.accounts);
+    return new InjectedWalletSession(provider, permission || result);
+  }
+
+  #bindProviderEvents() {
+    const provider = this.#provider;
+
+    // MetaMask-style provider events if Wind Wallet exposes them later.
+    if (typeof provider.on === "function") {
+      try {
+        provider.on("accountsChanged", (accounts) => {
+          const next = toPermissionLevel(accounts);
+          if (next) {
+            this.#permissionLevel = next;
+            this.#accountChangeListener?.(next);
+          }
+        });
+      } catch {}
+
+      try {
+        provider.on("disconnect", () => {
+          this.#closeListener?.();
+        });
+      } catch {}
+    }
+  }
+
+  setABICache(cache) {
+    this.#encodingOptions = { zlib, abiProvider: cache };
+  }
+
+  onAccountChange(listener) {
+    this.#accountChangeListener = listener;
+  }
+
+  onClose(listener) {
+    this.#closeListener = listener;
+  }
+
+  onError(listener) {
+    this.#errorListener = listener;
+  }
+
+  isOpen() {
+    return true;
+  }
+
+  close() {
+    // Injected browser sessions are page-scoped. No persistent socket to close.
+    this.#closeListener?.();
+  }
+
+  metadata() {
+    return { transport: "injected", wallet: "Wind Wallet" };
+  }
+
+  get permissionLevel() {
+    return this.#permissionLevel;
+  }
+
+  set permissionLevel(value) {
+    const perm = toPermissionLevel(value);
+    this.#permissionLevel = perm || value;
+  }
+
+  get actor() {
+    return this.#permissionLevel?.actor ?? Name.from("");
+  }
+
+  get permission() {
+    return this.#permissionLevel?.permission ?? Name.from("");
+  }
+
+  async request(method, params, timeoutMs) {
+    return await requestWithTimeout(this.#provider, method, params, timeoutMs);
+  }
+
+  /**
+   * Create a VSR signing request for a transaction and send to wallet.
+   * Matches WalletSession.transact().
+   */
+  async transact(args, options) {
+    const willBroadcast = typeof options?.broadcast === "boolean" ? options.broadcast : true;
+    const requestArgs = { ...args, chainId: InjectedWalletSession.ChainID };
+
+    const req = await SigningRequest.create(requestArgs, this.#encodingOptions);
+    req.setBroadcast(willBroadcast);
+
+    const vsr = req.encode(true, false, "vsr:");
+    return this.signRequest(vsr, options?.timeoutMs);
+  }
+
+  /**
+   * Send a VSR string to Wind Wallet approval UI.
+   */
+  async signRequest(vsr, timeoutMs) {
+    const payload = typeof vsr === "string" ? vsr : String(vsr || "");
+    let reply;
+
+    if (typeof this.#provider.signRequest === "function") {
+      reply = await withTimeout(
+        Promise.resolve(this.#provider.signRequest(payload)),
+        timeoutMs,
+        "signRequest"
+      );
+    } else {
+      reply = await this.request("signRequest", [payload], timeoutMs);
+    }
+
+    if (reply?.code === "SENT") return reply.result;
+    if (reply?.code === "SIGNED") return SignedTransaction.from(reply.result);
+    if (reply?.signatures || reply?.transaction) return SignedTransaction.from(reply);
+    if (reply?.transaction_id || reply?.processed) return reply;
+
+    throw replyError(reply, "Signing request rejected.");
+  }
+
+  async signMessage(message, timeoutMs) {
+    const reply = await this.request("vex_signMessage", [message], timeoutMs);
+
+    if (typeof reply === "string") return Signature.from(reply);
+    if (reply?.signature) return Signature.from(reply.signature);
+    if (reply?.code === "SIGNED" && reply?.result?.signature) {
+      return Signature.from(reply.result.signature);
+    }
+
+    throw replyError(reply, "Message signing rejected.");
+  }
+
+  async sharedSecret(publicKey, timeoutMs) {
+    const key = publicKey?.toString ? publicKey.toString() : String(publicKey || "");
+    const reply = await this.request("vex_sharedSecret", [key], timeoutMs);
+
+    if (typeof reply === "string") return Checksum512.from(reply);
+    if (reply?.secret) return Checksum512.from(reply.secret);
+    if (reply?.code === "CREATED" && reply?.result?.secret) {
+      return Checksum512.from(reply.result.secret);
+    }
+
+    throw replyError(reply, "Shared secret creation failed.");
+  }
+}
+
+/**
+ * Low-level helper for request({ method, params }) providers.
+ */
+export async function requestWithTimeout(provider, method, params, timeoutMs) {
+  if (!isRequestProvider(provider)) {
+    throw new Error("Wind Wallet injected provider is not available.");
+  }
+
+  const req = provider.request({
+    method: String(method || ""),
+    params: normalizeParams(params),
+  });
+
+  return await withTimeout(Promise.resolve(req), timeoutMs, method);
+}
+
+async function withTimeout(promise, timeoutMs, label = "request") {
+  const ms = normalizeTimeoutMs(timeoutMs, DEFAULT_TIMEOUT_MS);
+
+  return await new Promise((resolve, reject) => {
+    const timer = setTimer(() => {
+      reject(new Error(`${label} timed out.`));
+    }, ms);
+
+    promise.then(
+      (value) => {
+        clearTimer(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimer(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+/**
+ * WindClient
+ * Hybrid connector for DApps.
+ *
+ * connect() chooses:
+ * 1. Injected provider when opened inside Wind Wallet browser.
+ * 2. QR/VSR + PeerJS fallback when opened in a normal browser.
+ */
+export class WindClient {
+  #connector;
+  #listeners = new Map();
+  #options;
+
+  constructor(options = {}) {
+    this.#options = { preferInjected: true, ...options };
+  }
+
+  on(event, listener) {
+    this.#listeners.set(String(event || ""), listener);
+    if (this.#connector && typeof this.#connector.on === "function") {
+      this.#connector.on(event, listener);
+    }
+  }
+
+  off(event) {
+    this.#listeners.delete(String(event || ""));
+    if (this.#connector && typeof this.#connector.off === "function") {
+      this.#connector.off(event);
+    }
+  }
+
+  get connector() {
+    return this.#connector;
+  }
+
+  isInjectedAvailable() {
+    return isWindWalletInjected();
+  }
+
+  /**
+   * Connect to Wind Wallet.
+   *
+   * @param {{
+   *   name?: string,
+   *   icon?: string,
+   *   preferInjected?: boolean,
+   *   timeoutMs?: number,
+   *   walletUrl?: string,
+   *   openWallet?: (vsr:string, connector:WindConnector)=>void,
+   *   onLoginRequest?: (vsr:string, connector:WindConnector)=>void,
+   *   peerOptions?: any
+   * }=} options
+   *
+   * For non-injected fallback, pass onLoginRequest(vsr) to show QR/modal.
+   */
+  async connect(options = {}) {
+    const opts = { ...this.#options, ...options };
+
+    if (opts.preferInjected !== false && isWindWalletInjected()) {
+      const session = await InjectedWalletSession.connect({ timeoutMs: opts.timeoutMs });
+      this.#listeners.get("session")?.(session, { transport: "injected" });
+      return session;
+    }
+
+    const connector = new WindConnector(opts.peerOptions);
+    this.#connector = connector;
+
+    for (const [event, listener] of this.#listeners.entries()) {
+      connector.on(event, listener);
+    }
+
+    await connector.connect();
+    const vsr = connector.createLoginRequest(opts.name || "Wind DApp", opts.icon || "");
+
+    return await new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimer(timeout);
+      };
+
+      const timeout = setTimer(() => {
+        cleanup();
+        const err = new Error("Wind Wallet peer login timed out.");
+        err.vsr = vsr;
+        reject(err);
+      }, normalizeTimeoutMs(opts.timeoutMs, DEFAULT_TIMEOUT_MS));
+
+      connector.on("session", (session, proof) => {
+        cleanup();
+        this.#listeners.get("session")?.(session, proof);
+        resolve(session);
+      });
+
+      connector.on("error", (error) => {
+        this.#listeners.get("error")?.(error);
+      });
+
+      if (typeof opts.onLoginRequest === "function") {
+        opts.onLoginRequest(vsr, connector);
+        return;
+      }
+
+      if (typeof opts.openWallet === "function") {
+        opts.openWallet(vsr, connector);
+        return;
+      }
+
+      if (opts.walletUrl && typeof globalThis?.open === "function") {
+        const payload = vsr.startsWith("vsr:") ? vsr.slice(4) : vsr;
+        const url = `${String(opts.walletUrl).replace(/\/$/, "")}/login?vsr=${encodeURIComponent(payload)}`;
+        try {
+          globalThis.open(url, "Wind Wallet");
+        } catch {}
+        return;
+      }
+
+      // No UI handler was provided. Reject with the generated VSR so the DApp can render it.
+      const err = new Error(
+        "Wind Wallet injected provider not found. Show this VSR as QR or pass onLoginRequest(vsr)."
+      );
+      err.vsr = vsr;
+      err.connector = connector;
+      cleanup();
+      reject(err);
+    });
+  }
+}
+
+/**
+ * Convenience helper.
+ */
+export async function connectWindWallet(options = {}) {
+  const client = new WindClient(options);
+  return await client.connect(options);
+}