@usions/sdk 2.1.4 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "Usion Mini App SDK for iframe games and services",
   "type": "module",
   "main": "src/modules/index.js",
@@ -25,10 +25,12 @@
   "scripts": {
     "build": "rollup -c",
     "build:copy": "npm run build && cp src/browser.js ../../web/public/usion-sdk.js && cp src/browser.js ../../microservices/shared/usion-sdk.js",
-    "watch": "rollup -c --watch"
+    "watch": "rollup -c --watch",
+    "test": "npm run build && vitest run"
   },
   "devDependencies": {
-    "rollup": "^4.0.0"
+    "rollup": "^4.0.0",
+    "vitest": "^2.1.9"
   },
   "keywords": [
     "usion",

package/src/browser.js

@@ -13,6 +13,58 @@ var Usion = (function () {
     return ++_requestId;
   }
 
+  // Trusted origin of the host shell that embedded us (web iframe only).
+  // Resolved lazily from the real embedder, never from message contents.
+  let _parentOrigin = null;
+
+  function _resolveParentOrigin() {
+    try {
+      if (window.location.ancestorOrigins && window.location.ancestorOrigins.length) {
+        return window.location.ancestorOrigins[0];
+      }
+    } catch (e) { /* not supported */ }
+    try {
+      if (typeof document !== 'undefined' && document.referrer) {
+        return new URL(document.referrer).origin;
+      }
+    } catch (e) { /* malformed referrer */ }
+    return null;
+  }
+
+  /**
+   * Decide whether an incoming postMessage may be trusted.
+   *
+   * The host shell is the only legitimate sender. A sibling iframe or any other
+   * script on the page must NOT be able to forge messages (e.g. a fake
+   * PAYMENT_SUCCESS that unlocks paid value for free).
+   *
+   * - React Native WebView: messages are delivered in-process and carry no
+   *   usable origin/source, so they are trusted.
+   * - Web iframe: the only window that equals `window.parent` is the real
+   *   embedder. `event.source` is set by the browser and cannot be spoofed, so
+   *   `event.source === window.parent` rejects siblings and self-posts. We then
+   *   cross-check `event.origin` against the embedder's origin as defense-in-depth.
+   * - Not embedded (standalone / tests): nothing to protect against; allowed.
+   *
+   * @param {MessageEvent} event
+   * @returns {boolean}
+   */
+  function isTrustedMessageSource(event) {
+    if (typeof window === 'undefined') return true;
+    if (window.ReactNativeWebView) return true;
+    if (window.parent === window) return true;
+
+    if (event && event.source && event.source !== window.parent) return false;
+
+    if (_parentOrigin === null) {
+      _parentOrigin = _resolveParentOrigin();
+    }
+    if (_parentOrigin && event && event.origin && event.origin !== _parentOrigin) {
+      return false;
+    }
+    return true;
+  }
+
   /**
    * Core Usion object with init, _post, _request
    */
@@ -49,6 +101,9 @@ var Usion = (function () {
 
       // Setup global message handler
       window.addEventListener('message', function(event) {
+        // Reject messages from anything other than the host shell.
+        if (!isTrustedMessageSource(event)) return;
+
         let data;
         try {
           data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -394,6 +449,10 @@ var Usion = (function () {
 
           // Listen for response
           function handler(event) {
+            // Only honor payment results from the trusted host shell — a forged
+            // PAYMENT_SUCCESS must never resolve this promise.
+            if (!isTrustedMessageSource(event)) return;
+
             let response;
             try {
               response = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -780,6 +839,7 @@ var Usion = (function () {
    * Usion SDK Misc — submit, error, exit, share, log, on, requestPayment (legacy)
    */
 
+
   const miscMethods = {
     /**
      * Request payment from user (legacy method)
@@ -886,6 +946,8 @@ var Usion = (function () {
      */
     on: function(type, callback) {
       window.addEventListener('message', function(event) {
+        if (!isTrustedMessageSource(event)) return;
+
         let data;
         try {
           data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -1367,6 +1429,7 @@ var Usion = (function () {
    * Usion SDK Game Proxy — postMessage relay through parent app
    */
 
+
   /**
    * Add proxy connection methods to game module
    * @param {object} game - The game module object
@@ -1423,6 +1486,8 @@ var Usion = (function () {
       self._proxyListenerSetup = true;
 
       window.addEventListener('message', function(event) {
+        if (!isTrustedMessageSource(event)) return;
+
         var data;
         try {
           data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -1636,7 +1701,10 @@ var Usion = (function () {
       const self = this;
 
       if (self.directMode) {
-        self._sendDirect(actionType || 'action', actionData || {});
+        self._sendDirect('action', {
+          action_type: actionType || 'default',
+          action_data: actionData || {}
+        });
         return Promise.resolve({ success: true });
       }
 
@@ -1836,6 +1904,109 @@ var Usion = (function () {
       }
     };
 
+    // ───────────────────────────────────────────────────────────
+    // Cross-reload state persistence
+    // ───────────────────────────────────────────────────────────
+    // When a mini-app's iframe is unmounted and later re-mounted (e.g. the
+    // user navigates back to the chat and re-opens the game from the same
+    // room), the entire JS context is destroyed. Server-side room state is
+    // preserved, but anything the game holds in memory — board state, phase,
+    // whose turn it is, placement choices — is lost. The platform sync
+    // mechanism only replays raw actions; reconstructing client-visible
+    // state from a zero baseline is fragile or impossible.
+    //
+    // These helpers give every game a uniform way to snapshot whatever it
+    // needs to localStorage. Keys are scoped to (player_id, room_id) so a
+    // single browser can hold independent state for different rooms or
+    // accounts without collision, and "play a different match in the same
+    // room" naturally collides — which is the correct outcome.
+
+    const STATE_KEY_PREFIX = '_usion_game_state:';
+
+    function _stateKey(self) {
+      const rid = self.roomId || (Usion.config && Usion.config.roomId);
+      const pid = self.playerId
+        || (Usion.user && typeof Usion.user.getId === 'function' && Usion.user.getId())
+        || (Usion.config && Usion.config.userId);
+      if (!rid || !pid) return null;
+      return STATE_KEY_PREFIX + pid + ':' + rid;
+    }
+
+    /**
+     * Persist arbitrary JSON-serializable game state across iframe reloads.
+     * The mini-app decides the schema; the SDK only stores/retrieves.
+     * @param {*} state - Any JSON-serializable value
+     * @returns {boolean} true if saved, false if not (no room/player yet, or storage error)
+     */
+    game.saveState = function(state) {
+      const self = this;
+      const key = _stateKey(self);
+      if (!key) return false;
+      try {
+        localStorage.setItem(key, JSON.stringify({ state: state, savedAt: Date.now() }));
+        return true;
+      } catch (e) {
+        // Quota exceeded, private-mode rejection, etc. — non-fatal.
+        return false;
+      }
+    };
+
+    /**
+     * Retrieve previously-saved state for the current (player, room).
+     * @returns {*} The saved state value, or null if none / unreadable.
+     */
+    game.loadState = function() {
+      const self = this;
+      const key = _stateKey(self);
+      if (!key) return null;
+      try {
+        const raw = localStorage.getItem(key);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        return parsed && parsed.state !== undefined ? parsed.state : null;
+      } catch (e) {
+        return null;
+      }
+    };
+
+    /**
+     * Drop any persisted state for the current (player, room).
+     * Call this when the game ends or starts fresh, so the next iframe
+     * mount in the same room doesn't pick up stale data.
+     */
+    game.clearState = function() {
+      const self = this;
+      const key = _stateKey(self);
+      if (!key) return;
+      try { localStorage.removeItem(key); } catch (e) { /* non-fatal */ }
+    };
+
+    /**
+     * Forward a debug snapshot to the parent platform. The platform renders
+     * it in a top-right overlay when the iframe host is opened with
+     * `?debug=1`. The payload schema is up to the game — anything JSON-
+     * serializable. No-op when not running inside an iframe.
+     *
+     * Games should call this at every meaningful state transition (turn
+     * change, action sent, action received, sync, phase change, etc.) so
+     * the overlay reflects live state.
+     *
+     * @param {object} payload - Arbitrary JSON-serializable debug data
+     */
+    game.debug = function(payload) {
+      try {
+        // Must work in both web iframes (window.parent !== window) and
+        // React Native WebView (window.parent === window, but a host bridge
+        // exists at window.ReactNativeWebView). Usion._post handles routing
+        // for both; this guard just avoids no-op work in standalone pages.
+        var inFrame = window.parent && window.parent !== window;
+        var inRNWebView = !!window.ReactNativeWebView;
+        if (inFrame || inRNWebView) {
+          Usion._post({ type: 'GAME_DEBUG', payload: payload || {} });
+        }
+      } catch (e) { /* non-fatal */ }
+    };
+
     /**
      * Get connection status
      * @returns {boolean}
@@ -1890,17 +2061,6 @@ var Usion = (function () {
           return self.connectDirect();
         }
 
-        // Use config values as defaults
-        socketUrl = socketUrl || Usion.config.socketUrl;
-        token = token || Usion.user.getToken();
-
-        if (!socketUrl) {
-          return Promise.reject(new Error('No socket URL provided'));
-        }
-        if (!token) {
-          return Promise.reject(new Error('No auth token available'));
-        }
-
         // If already connected (direct or proxy), return immediately
         if (self._useProxy && self.connected) {
           return Promise.resolve();
@@ -1915,6 +2075,7 @@ var Usion = (function () {
         }
 
         // When running inside an iframe or WebView, use parent as socket proxy
+        // (checked BEFORE token validation — iframe games don't need a token)
         var isInFrame = !!window.__USION_PROXY__
                      || window.parent !== window
                      || !!window.ReactNativeWebView
@@ -1925,6 +2086,17 @@ var Usion = (function () {
           return self._connectViaProxy();
         }
 
+        // Use config values as defaults (only for direct socket connections)
+        socketUrl = socketUrl || Usion.config.socketUrl;
+        token = token || Usion.user.getToken();
+
+        if (!socketUrl) {
+          return Promise.reject(new Error('No socket URL provided'));
+        }
+        if (!token) {
+          return Promise.reject(new Error('No auth token available'));
+        }
+
         self._connecting = true;
         self._connectPromise = new Promise(function(resolve, reject) {
           // Check if socket.io-client is available

package/src/modules/core.js

@@ -10,6 +10,58 @@ export function getNextRequestId() {
   return ++_requestId;
 }
 
+// Trusted origin of the host shell that embedded us (web iframe only).
+// Resolved lazily from the real embedder, never from message contents.
+let _parentOrigin = null;
+
+function _resolveParentOrigin() {
+  try {
+    if (window.location.ancestorOrigins && window.location.ancestorOrigins.length) {
+      return window.location.ancestorOrigins[0];
+    }
+  } catch (e) { /* not supported */ }
+  try {
+    if (typeof document !== 'undefined' && document.referrer) {
+      return new URL(document.referrer).origin;
+    }
+  } catch (e) { /* malformed referrer */ }
+  return null;
+}
+
+/**
+ * Decide whether an incoming postMessage may be trusted.
+ *
+ * The host shell is the only legitimate sender. A sibling iframe or any other
+ * script on the page must NOT be able to forge messages (e.g. a fake
+ * PAYMENT_SUCCESS that unlocks paid value for free).
+ *
+ * - React Native WebView: messages are delivered in-process and carry no
+ *   usable origin/source, so they are trusted.
+ * - Web iframe: the only window that equals `window.parent` is the real
+ *   embedder. `event.source` is set by the browser and cannot be spoofed, so
+ *   `event.source === window.parent` rejects siblings and self-posts. We then
+ *   cross-check `event.origin` against the embedder's origin as defense-in-depth.
+ * - Not embedded (standalone / tests): nothing to protect against; allowed.
+ *
+ * @param {MessageEvent} event
+ * @returns {boolean}
+ */
+export function isTrustedMessageSource(event) {
+  if (typeof window === 'undefined') return true;
+  if (window.ReactNativeWebView) return true;
+  if (window.parent === window) return true;
+
+  if (event && event.source && event.source !== window.parent) return false;
+
+  if (_parentOrigin === null) {
+    _parentOrigin = _resolveParentOrigin();
+  }
+  if (_parentOrigin && event && event.origin && event.origin !== _parentOrigin) {
+    return false;
+  }
+  return true;
+}
+
 /**
  * Core Usion object with init, _post, _request
  */
@@ -46,6 +98,9 @@ export const core = {
 
     // Setup global message handler
     window.addEventListener('message', function(event) {
+      // Reject messages from anything other than the host shell.
+      if (!isTrustedMessageSource(event)) return;
+
       let data;
       try {
         data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;

package/src/modules/game-core.js

@@ -44,17 +44,6 @@ export function createGameModule(Usion) {
         return self.connectDirect();
       }
 
-      // Use config values as defaults
-      socketUrl = socketUrl || Usion.config.socketUrl;
-      token = token || Usion.user.getToken();
-
-      if (!socketUrl) {
-        return Promise.reject(new Error('No socket URL provided'));
-      }
-      if (!token) {
-        return Promise.reject(new Error('No auth token available'));
-      }
-
       // If already connected (direct or proxy), return immediately
       if (self._useProxy && self.connected) {
         return Promise.resolve();
@@ -69,6 +58,7 @@ export function createGameModule(Usion) {
       }
 
       // When running inside an iframe or WebView, use parent as socket proxy
+      // (checked BEFORE token validation — iframe games don't need a token)
       var isInFrame = !!window.__USION_PROXY__
                    || window.parent !== window
                    || !!window.ReactNativeWebView
@@ -79,6 +69,17 @@ export function createGameModule(Usion) {
         return self._connectViaProxy();
       }
 
+      // Use config values as defaults (only for direct socket connections)
+      socketUrl = socketUrl || Usion.config.socketUrl;
+      token = token || Usion.user.getToken();
+
+      if (!socketUrl) {
+        return Promise.reject(new Error('No socket URL provided'));
+      }
+      if (!token) {
+        return Promise.reject(new Error('No auth token available'));
+      }
+
       self._connecting = true;
       self._connectPromise = new Promise(function(resolve, reject) {
         // Check if socket.io-client is available

package/src/modules/game-methods.js

@@ -121,7 +121,10 @@ export function applyGameMethods(game, Usion) {
     const self = this;
 
     if (self.directMode) {
-      self._sendDirect(actionType || 'action', actionData || {});
+      self._sendDirect('action', {
+        action_type: actionType || 'default',
+        action_data: actionData || {}
+      });
       return Promise.resolve({ success: true });
     }
 
@@ -321,6 +324,109 @@ export function applyGameMethods(game, Usion) {
     }
   };
 
+  // ───────────────────────────────────────────────────────────
+  // Cross-reload state persistence
+  // ───────────────────────────────────────────────────────────
+  // When a mini-app's iframe is unmounted and later re-mounted (e.g. the
+  // user navigates back to the chat and re-opens the game from the same
+  // room), the entire JS context is destroyed. Server-side room state is
+  // preserved, but anything the game holds in memory — board state, phase,
+  // whose turn it is, placement choices — is lost. The platform sync
+  // mechanism only replays raw actions; reconstructing client-visible
+  // state from a zero baseline is fragile or impossible.
+  //
+  // These helpers give every game a uniform way to snapshot whatever it
+  // needs to localStorage. Keys are scoped to (player_id, room_id) so a
+  // single browser can hold independent state for different rooms or
+  // accounts without collision, and "play a different match in the same
+  // room" naturally collides — which is the correct outcome.
+
+  const STATE_KEY_PREFIX = '_usion_game_state:';
+
+  function _stateKey(self) {
+    const rid = self.roomId || (Usion.config && Usion.config.roomId);
+    const pid = self.playerId
+      || (Usion.user && typeof Usion.user.getId === 'function' && Usion.user.getId())
+      || (Usion.config && Usion.config.userId);
+    if (!rid || !pid) return null;
+    return STATE_KEY_PREFIX + pid + ':' + rid;
+  }
+
+  /**
+   * Persist arbitrary JSON-serializable game state across iframe reloads.
+   * The mini-app decides the schema; the SDK only stores/retrieves.
+   * @param {*} state - Any JSON-serializable value
+   * @returns {boolean} true if saved, false if not (no room/player yet, or storage error)
+   */
+  game.saveState = function(state) {
+    const self = this;
+    const key = _stateKey(self);
+    if (!key) return false;
+    try {
+      localStorage.setItem(key, JSON.stringify({ state: state, savedAt: Date.now() }));
+      return true;
+    } catch (e) {
+      // Quota exceeded, private-mode rejection, etc. — non-fatal.
+      return false;
+    }
+  };
+
+  /**
+   * Retrieve previously-saved state for the current (player, room).
+   * @returns {*} The saved state value, or null if none / unreadable.
+   */
+  game.loadState = function() {
+    const self = this;
+    const key = _stateKey(self);
+    if (!key) return null;
+    try {
+      const raw = localStorage.getItem(key);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      return parsed && parsed.state !== undefined ? parsed.state : null;
+    } catch (e) {
+      return null;
+    }
+  };
+
+  /**
+   * Drop any persisted state for the current (player, room).
+   * Call this when the game ends or starts fresh, so the next iframe
+   * mount in the same room doesn't pick up stale data.
+   */
+  game.clearState = function() {
+    const self = this;
+    const key = _stateKey(self);
+    if (!key) return;
+    try { localStorage.removeItem(key); } catch (e) { /* non-fatal */ }
+  };
+
+  /**
+   * Forward a debug snapshot to the parent platform. The platform renders
+   * it in a top-right overlay when the iframe host is opened with
+   * `?debug=1`. The payload schema is up to the game — anything JSON-
+   * serializable. No-op when not running inside an iframe.
+   *
+   * Games should call this at every meaningful state transition (turn
+   * change, action sent, action received, sync, phase change, etc.) so
+   * the overlay reflects live state.
+   *
+   * @param {object} payload - Arbitrary JSON-serializable debug data
+   */
+  game.debug = function(payload) {
+    try {
+      // Must work in both web iframes (window.parent !== window) and
+      // React Native WebView (window.parent === window, but a host bridge
+      // exists at window.ReactNativeWebView). Usion._post handles routing
+      // for both; this guard just avoids no-op work in standalone pages.
+      var inFrame = window.parent && window.parent !== window;
+      var inRNWebView = !!window.ReactNativeWebView;
+      if (inFrame || inRNWebView) {
+        Usion._post({ type: 'GAME_DEBUG', payload: payload || {} });
+      }
+    } catch (e) { /* non-fatal */ }
+  };
+
   /**
    * Get connection status
    * @returns {boolean}

package/src/modules/game-proxy.js

@@ -2,6 +2,8 @@
  * Usion SDK Game Proxy — postMessage relay through parent app
  */
 
+import { isTrustedMessageSource } from './core.js';
+
 /**
  * Add proxy connection methods to game module
  * @param {object} game - The game module object
@@ -58,6 +60,8 @@ export function applyGameProxy(game, Usion) {
     self._proxyListenerSetup = true;
 
     window.addEventListener('message', function(event) {
+      if (!isTrustedMessageSource(event)) return;
+
       var data;
       try {
         data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;

package/src/modules/misc.js

@@ -2,6 +2,8 @@
  * Usion SDK Misc — submit, error, exit, share, log, on, requestPayment (legacy)
  */
 
+import { isTrustedMessageSource } from './core.js';
+
 export const miscMethods = {
   /**
    * Request payment from user (legacy method)
@@ -108,6 +110,8 @@ export const miscMethods = {
    */
   on: function(type, callback) {
     window.addEventListener('message', function(event) {
+      if (!isTrustedMessageSource(event)) return;
+
       let data;
       try {
         data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;

package/src/modules/wallet.js

@@ -2,7 +2,7 @@
  * Usion SDK Wallet Module — wallet and payment operations
  */
 
-import { getNextRequestId } from './core.js';
+import { getNextRequestId, isTrustedMessageSource } from './core.js';
 
 /**
  * @param {object} Usion - Reference to the main Usion object
@@ -57,6 +57,10 @@ export function createWalletModule(Usion) {
 
         // Listen for response
         function handler(event) {
+          // Only honor payment results from the trusted host shell — a forged
+          // PAYMENT_SUCCESS must never resolve this promise.
+          if (!isTrustedMessageSource(event)) return;
+
           let response;
           try {
             response = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;

package/types/index.d.ts

@@ -213,6 +213,16 @@ export interface GameModule {
   requestRematch(): void;
   forfeit(): Promise<{ success: boolean; error?: string }>;
 
+  // Persisted state — survives iframe unmount/remount.
+  // Keyed by (player_id, room_id) in localStorage. Schema is up to the game.
+  saveState<T = any>(state: T): boolean;
+  loadState<T = any>(): T | null;
+  clearState(): void;
+
+  // Forward a debug snapshot to the parent. Rendered as a top-right
+  // overlay over the iframe when the host page is opened with `?debug=1`.
+  debug(payload: Record<string, any>): void;
+
   // Event handlers
   onJoined(callback: (data: GameJoinResult) => void): void;
   onPlayerJoined(callback: (data: PlayerJoinedData) => void): void;
@@ -306,6 +316,10 @@ export interface UsionSDK {
 
   // Sharing
   share(contentType: 'audio' | 'image' | 'video' | 'text' | 'mixed', data: ShareData): void;
+  shareToFeed(contentType: 'text' | 'image' | 'video' | 'audio' | 'mixed', data: {
+    text?: string;
+    media?: Array<{ type: 'image' | 'video' | 'audio'; url: string; thumbnailUrl?: string; width?: number; height?: number; duration?: number }>;
+  }): Promise<{ success: boolean; postId?: string; shareUrl?: string }>;
 
   // Logging
   log(msg: string): void;