@mywallpaper/addon-sdk 2.6.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mywallpaper/addon-sdk",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "SDK for building MyWallpaper addons - TypeScript types, manifest validation, and utilities",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist",
+    "src/runtime",
     "README.md",
     "LICENSE"
   ],
@@ -64,4 +65,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/src/runtime/addon-client.js

@@ -0,0 +1,489 @@
+/* eslint-disable no-var, curly, object-shorthand */
+/**
+ * MyWallpaper Addon SDK v2.0
+ *
+ * API disponible pour les addons:
+ * - window.MyWallpaper.config          → Configuration actuelle
+ * - window.MyWallpaper.layerId         → ID du layer
+ * - window.MyWallpaper.onSettingsChange(fn) → Callback hot-reload
+ * - window.MyWallpaper.onEvent(type, fn)    → Événements système
+ * - window.MyWallpaper.ready(options)       → Signal prêt
+ * - window.MyWallpaper.renderComplete()     → Signal rendu visuel terminé
+ *
+ * Note: Uses 'var' intentionally for maximum iframe/browser compatibility
+ */
+; (function () {
+  'use strict'
+
+  var layerId = window.__MYWALLPAPER_LAYER_ID__ || ''
+  var config = window.__MYWALLPAPER_INITIAL_CONFIG__ || {}
+  var isReady = false
+  var isRenderComplete = false
+
+  var settingsCallbacks = []
+  var eventCallbacks = new Map()
+  var lifecycleCallbacks = { mount: [], unmount: [], pause: [], resume: [] }
+  var pendingStorage = new Map()
+  var pendingPermissions = new Map()
+  var pendingNetwork = new Map()
+  var pendingOAuth = new Map()
+  var pendingOAuthScopes = new Map()
+  var pendingFileAccess = new Map()
+  var grantedBlobUrls = new Map() // settingKey -> blobUrl
+
+  // Get the original fetch saved by network-sandbox.js (before it was blocked)
+  var originalFetch = window.__MYWALLPAPER_ORIGINAL_FETCH__ || null
+
+  // Message handler
+  function onMessage(e) {
+    if (e.source !== window.parent) return
+    var d = e.data
+    if (!d || d.source !== 'MyWallpaperHost') return
+
+    switch (d.type) {
+      case 'SETTINGS_UPDATE':
+        var p = d.payload || d
+        config = p.settings || p
+        var keys = p.changedKeys || Object.keys(config)
+        settingsCallbacks.forEach(function (cb) {
+          try { cb(config, keys) } catch (err) { console.error('[MyWallpaper]', err) }
+        })
+        break
+
+      case 'SYSTEM_EVENT':
+        var cbs = eventCallbacks.get(d.payload.event)
+        if (cbs) cbs.forEach(function (cb) {
+          try { cb(d.payload.data) } catch (err) { console.error('[MyWallpaper]', err) }
+        })
+        break
+
+      case 'LIFECYCLE':
+        var lcbs = lifecycleCallbacks[d.payload.event]
+        if (lcbs) lcbs.forEach(function (cb) {
+          try { cb() } catch (err) { console.error('[MyWallpaper]', err) }
+        })
+        break
+
+      case 'STORAGE_RESPONSE':
+        var op = pendingStorage.get(d.payload.requestId)
+        if (op) {
+          pendingStorage.delete(d.payload.requestId)
+          d.payload.success ? op.resolve(d.payload.value) : op.reject(new Error(d.payload.error))
+        }
+        break
+
+      case 'PERMISSION_GRANT':
+        var permOp = pendingPermissions.get(d.payload.requestId)
+        if (permOp) {
+          pendingPermissions.delete(d.payload.requestId)
+          permOp(d.payload.granted === true)
+        }
+        break
+
+      case 'NETWORK_RESPONSE':
+        var netOp = pendingNetwork.get(d.payload.requestId)
+        if (netOp) {
+          pendingNetwork.delete(d.payload.requestId)
+          if (d.payload.success) {
+            netOp.resolve({
+              ok: d.payload.status >= 200 && d.payload.status < 300,
+              status: d.payload.status || 200,
+              statusText: d.payload.statusText || 'OK',
+              headers: d.payload.headers || {},
+              data: d.payload.data
+            })
+          } else {
+            netOp.reject(new Error(d.payload.error || 'Network request failed'))
+          }
+        }
+        break
+
+      case 'OAUTH_RESPONSE':
+        var oauthOp = pendingOAuth.get(d.payload.requestId)
+        if (oauthOp) {
+          pendingOAuth.delete(d.payload.requestId)
+          if (d.payload.success) {
+            // Check if it's a scopes error
+            if (d.payload.error === 'insufficient_scopes') {
+              oauthOp.resolve({
+                error: 'insufficient_scopes',
+                message: d.payload.message,
+                provider: d.payload.provider,
+                missingScopes: d.payload.missing_scopes || d.payload.missingScopes || [],
+                requiredScopes: d.payload.required_scopes || d.payload.requiredScopes || []
+              })
+            } else {
+              oauthOp.resolve({
+                ok: d.payload.status >= 200 && d.payload.status < 300,
+                status: d.payload.status || 200,
+                headers: d.payload.headers || {},
+                data: d.payload.data
+              })
+            }
+          } else {
+            // Check if it's a scopes error from failed request
+            if (d.payload.error === 'insufficient_scopes' ||
+              (d.payload.data && d.payload.data.error === 'insufficient_scopes')) {
+              var scopesData = d.payload.data || d.payload
+              oauthOp.resolve({
+                error: 'insufficient_scopes',
+                message: scopesData.message || 'Insufficient OAuth scopes',
+                provider: scopesData.provider,
+                missingScopes: scopesData.missing_scopes || scopesData.missingScopes || [],
+                requiredScopes: scopesData.required_scopes || scopesData.requiredScopes || []
+              })
+            } else {
+              oauthOp.reject(new Error(d.payload.error || 'OAuth request failed'))
+            }
+          }
+        }
+        break
+
+      case 'OAUTH_SCOPES_GRANT':
+        var scopeResolver = pendingOAuthScopes.get(d.payload.requestId)
+        if (scopeResolver) {
+          pendingOAuthScopes.delete(d.payload.requestId)
+          scopeResolver(d.payload.granted === true)
+        }
+        break
+
+      case 'FILE_ACCESS_RESPONSE':
+        // Handle file access response from host
+        // Host sends us a Blob object (cloned via structured clone)
+        // We create our own blob URL from it
+        var fileOp = pendingFileAccess.get(d.requestId)
+        if (fileOp) {
+          pendingFileAccess.delete(d.requestId)
+          if (d.granted && d.blob instanceof Blob) {
+            // Create our own blob URL from the received Blob
+            var blobUrl = URL.createObjectURL(d.blob)
+            grantedBlobUrls.set(d.settingKey, blobUrl)
+            fileOp.resolve({ granted: true, blobUrl: blobUrl })
+          } else {
+            fileOp.resolve({ granted: false, error: d.error || 'Access denied' })
+          }
+        }
+        break
+    }
+  }
+
+  function send(type, payload) {
+    window.parent.postMessage({ type: type, layerId: layerId, timestamp: Date.now(), payload: payload }, '*')
+  }
+
+  function storageOp(op, key, value) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingStorage.set(id, { resolve: resolve, reject: reject })
+      setTimeout(function () {
+        if (pendingStorage.has(id)) {
+          pendingStorage.delete(id)
+          reject(new Error('Storage timeout'))
+        }
+      }, 5000)
+      send('STORAGE_OPERATION', { operation: op, key: key, value: value, requestId: id })
+    })
+  }
+
+  /**
+   * Network fetch via secure host proxy
+   * This is the ONLY way addons can make network requests
+   * Domain must be declared in manifest.json permissions.network.domains
+   */
+  function networkFetch(url, options) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingNetwork.set(id, { resolve: resolve, reject: reject })
+      // 30s timeout for network requests
+      setTimeout(function () {
+        if (pendingNetwork.has(id)) {
+          pendingNetwork.delete(id)
+          reject(new Error('Network request timeout (30s)'))
+        }
+      }, 30000)
+      options = options || {}
+      send('NETWORK_REQUEST', {
+        url: url,
+        method: options.method || 'GET',
+        headers: options.headers,
+        body: options.body,
+        requestId: id
+      })
+    })
+  }
+
+  /**
+   * OAuth API request via secure host proxy
+   * Makes authenticated API calls to OAuth providers (GitHub, Google, etc.)
+   * Tokens are stored securely on the server - never exposed to addons
+   *
+   * @param {string} provider - OAuth provider ('github', 'google', 'discord', 'spotify', 'twitch')
+   * @param {string} endpoint - API endpoint path (e.g., '/user', '/user/repos')
+   * @param {object} options - Request options (method, body, headers, requiredScopes)
+   */
+  function oauthRequest(provider, endpoint, options) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingOAuth.set(id, { resolve: resolve, reject: reject })
+      // 30s timeout for OAuth requests
+      setTimeout(function () {
+        if (pendingOAuth.has(id)) {
+          pendingOAuth.delete(id)
+          reject(new Error('OAuth request timeout (30s)'))
+        }
+      }, 30000)
+      options = options || {}
+      send('OAUTH_REQUEST', {
+        provider: provider,
+        endpoint: endpoint,
+        method: options.method || 'GET',
+        body: options.body,
+        headers: options.headers,
+        requiredScopes: options.requiredScopes || [],
+        requestId: id
+      })
+    })
+  }
+
+  /**
+   * Get the scopes granted for a connected OAuth provider
+   * Returns an empty array if not connected
+   *
+   * @param {string} provider - OAuth provider
+   * @returns {Promise<string[]>} Array of granted scopes
+   */
+  function oauthGetScopes(provider) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      var handler = function (e) {
+        if (e.source !== window.parent) return
+        var d = e.data
+        if (!d || d.source !== 'MyWallpaperHost') return
+        if (d.type === 'OAUTH_SCOPES_RESPONSE' && d.payload.requestId === id) {
+          window.removeEventListener('message', handler)
+          if (d.payload.success) {
+            resolve(d.payload.scopes || [])
+          } else {
+            reject(new Error(d.payload.error || 'Failed to get scopes'))
+          }
+        }
+      }
+      window.addEventListener('message', handler)
+      // 10s timeout
+      setTimeout(function () {
+        window.removeEventListener('message', handler)
+        resolve([]) // Return empty array on timeout (not connected)
+      }, 10000)
+      send('OAUTH_GET_SCOPES', { provider: provider, requestId: id })
+    })
+  }
+
+  /**
+   * Request re-authorization with additional scopes
+   * Opens the OAuth flow with new scopes while preserving existing ones
+   *
+   * @param {string} provider - OAuth provider
+   * @param {string[]} scopes - Additional scopes to request
+   * @param {string} reason - Reason shown to user
+   * @returns {Promise<boolean>} True if re-auth was successful
+   */
+  function oauthRequestScopes(provider, scopes, reason) {
+    return new Promise(function (resolve) {
+      var requestId = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingOAuthScopes.set(requestId, resolve)
+      // 60s timeout - user needs time to complete OAuth flow
+      setTimeout(function () {
+        if (pendingOAuthScopes.has(requestId)) {
+          pendingOAuthScopes.delete(requestId)
+          resolve(false)
+        }
+      }, 60000)
+      send('OAUTH_REQUEST_SCOPES', { provider: provider, scopes: scopes, reason: reason, requestId: requestId })
+    })
+  }
+
+  window.addEventListener('message', onMessage)
+
+  window.MyWallpaper = {
+    get config() { return config },
+    layerId: layerId,
+    version: '2.5',
+
+    onSettingsChange: function (fn) { if (typeof fn === 'function') settingsCallbacks.push(fn) },
+
+    onEvent: function (event, fn) {
+      if (typeof fn !== 'function') return
+      if (!eventCallbacks.has(event)) eventCallbacks.set(event, new Set())
+      eventCallbacks.get(event).add(fn)
+    },
+
+    offEvent: function (event, fn) {
+      var cbs = eventCallbacks.get(event)
+      if (cbs) cbs.delete(fn)
+    },
+
+    onMount: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.mount.push(fn) },
+    onUnmount: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.unmount.push(fn) },
+    onPause: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.pause.push(fn) },
+    onResume: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.resume.push(fn) },
+
+    ready: function (opts) {
+      if (isReady) return
+      isReady = true
+      opts = opts || {}
+      send('ADDON_READY', {
+        version: '2.5',
+        capabilities: opts.capabilities || [],
+        subscribedEvents: opts.subscribedEvents || []
+      })
+    },
+
+    requestPermission: function (perm, reason) {
+      return new Promise(function (resolve) {
+        var requestId = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+        pendingPermissions.set(requestId, resolve)
+        // 30s timeout - user needs time to see and respond to permission modal
+        setTimeout(function () {
+          if (pendingPermissions.has(requestId)) {
+            pendingPermissions.delete(requestId)
+            resolve(false) // Timeout = denied
+          }
+        }, 30000)
+        send('REQUEST_PERMISSION', { permission: perm, reason: reason, requestId: requestId })
+      })
+    },
+
+    renderComplete: function () {
+      if (isRenderComplete) return
+      isRenderComplete = true
+      var renderTimeMs = Math.round(performance.now())
+      send('RENDER_COMPLETE', { renderTimeMs: renderTimeMs })
+    },
+
+    storage: {
+      get: function (k) { return storageOp('get', k) },
+      set: function (k, v) { return storageOp('set', k, v) },
+      delete: function (k) { return storageOp('delete', k) },
+      clear: function () { return storageOp('clear') },
+      keys: function () { return storageOp('keys') },
+      size: function () { return storageOp('size') }
+    },
+
+    /**
+     * Network API - Secure proxy for HTTP requests
+     * All requests go through the host which validates domain whitelist
+     *
+     * @example
+     * // manifest.json: "permissions": { "network": { "domains": ["api.weather.com"] } }
+     * const response = await MyWallpaper.network.fetch('https://api.weather.com/current')
+     * if (response.ok) console.log(response.data)
+     */
+    network: {
+      fetch: networkFetch
+    },
+
+    /**
+     * OAuth API - Secure authenticated API calls to OAuth providers
+     * Tokens are stored securely on the server - never exposed to addons
+     *
+     * Supported providers: github, google, discord, spotify, twitch
+     *
+     * @example
+     * // First request permission
+     * const granted = await MyWallpaper.requestPermission('oauth:github', 'To display your GitHub profile')
+     * if (granted) {
+     *   // Make authenticated API request
+     *   const response = await MyWallpaper.oauth.request('github', '/user')
+     *   if (response.ok) console.log('GitHub user:', response.data)
+     *
+     *   // List repositories (with required scopes)
+     *   const repos = await MyWallpaper.oauth.request('github', '/user/repos', {
+     *     requiredScopes: ['repo']  // Will return scope error if missing
+     *   })
+     *   if (repos.error === 'insufficient_scopes') {
+     *     // Request additional scopes
+     *     const granted = await MyWallpaper.oauth.requestScopes('github', repos.missingScopes, 'Access private repos')
+     *     if (granted) {
+     *       // Retry request
+     *       const repos = await MyWallpaper.oauth.request('github', '/user/repos', { requiredScopes: ['repo'] })
+     *     }
+     *   }
+     * }
+     */
+    oauth: {
+      request: oauthRequest,
+      getScopes: oauthGetScopes,
+      requestScopes: oauthRequestScopes,
+      isConnected: function (provider) {
+        // Check connection by getting scopes - if scopes array is returned, provider is connected
+        return oauthGetScopes(provider)
+          .then(function (scopes) { return scopes.length > 0 })
+          .catch(function () { return false })
+      }
+    },
+
+    /**
+     * File Access API - Request access to user-uploaded files
+     * Files are not sent automatically - the addon must request access
+     * A modal is shown to the user EVERY TIME (not persisted)
+     *
+     * @example
+     * const videoRef = MyWallpaper.config.backgroundVideo
+     * if (MyWallpaper.files.isFileReference(videoRef)) {
+     *   const result = await MyWallpaper.files.request('backgroundVideo')
+     *   if (result.granted) {
+     *     video.src = result.blobUrl
+     *   }
+     * }
+     */
+    files: {
+      /**
+       * Check if a value is a file reference placeholder
+       * @param {unknown} value - Any value from config
+       * @returns {boolean} true if this is a FileReference
+       */
+      isFileReference: function (value) {
+        return value !== null &&
+          typeof value === 'object' &&
+          value.__type === 'file-reference' &&
+          typeof value.settingKey === 'string'
+      },
+
+      /**
+       * Request access to a file from the user
+       * Shows a modal asking for permission (every time)
+       * @param {string} settingKey - The setting key containing the file reference
+       * @returns {Promise<{granted: boolean, blobUrl?: string, error?: string}>}
+       */
+      request: function (settingKey) {
+        return new Promise(function (resolve) {
+          var requestId = Date.now() + '-' + Math.random().toString(36).slice(2)
+          pendingFileAccess.set(requestId, { resolve: resolve })
+          // 60s timeout - user needs time to respond to modal
+          setTimeout(function () {
+            if (pendingFileAccess.has(requestId)) {
+              pendingFileAccess.delete(requestId)
+              resolve({ granted: false, error: 'Request timeout' })
+            }
+          }, 60000)
+          send('FILE_ACCESS_REQUEST', { settingKey: settingKey, requestId: requestId })
+        })
+      },
+
+      /**
+       * Revoke access to a previously granted file
+       * The blob URL will be invalidated
+       * @param {string} settingKey - The setting key to revoke access for
+       */
+      revoke: function (settingKey) {
+        var blobUrl = grantedBlobUrls.get(settingKey)
+        if (blobUrl) {
+          URL.revokeObjectURL(blobUrl)
+          grantedBlobUrls.delete(settingKey)
+        }
+      }
+    }
+  }
+
+  console.warn('[MyWallpaper] SDK v2.5 ready:', layerId)
+})()

package/src/runtime/network-sandbox.js

@@ -0,0 +1,153 @@
+/**
+ * Network Sandbox Script - SECURITY LAYER
+ *
+ * This script MUST be injected FIRST (before addon-client.js)
+ * It saves original fetch/XHR for the SDK, then blocks them for addon code.
+ *
+ * Flow:
+ * 1. Save original fetch/XMLHttpRequest to __MYWALLPAPER_ORIGINAL_*
+ * 2. After addon-client.js loads, it will use these for the proxy
+ * 3. Replace window.fetch and XMLHttpRequest with blocked versions
+ * 4. Addon code must use MyWallpaper.network.fetch() instead
+ */
+;(function() {
+  'use strict';
+
+  // ============================================================================
+  // STEP 1: Save original network APIs for SDK internal use
+  // ============================================================================
+
+  // These will be used by the SDK's network proxy
+  window.__MYWALLPAPER_ORIGINAL_FETCH__ = window.fetch;
+  window.__MYWALLPAPER_ORIGINAL_XHR__ = window.XMLHttpRequest;
+
+  // ============================================================================
+  // STEP 2: Create blocked versions with helpful error messages
+  // ============================================================================
+
+  const BLOCKED_MESSAGE =
+    '[MyWallpaper Security] Direct network access is blocked for security.\n' +
+    'Use window.MyWallpaper.network.fetch(url, options) instead.\n\n' +
+    'Example:\n' +
+    '  const response = await MyWallpaper.network.fetch("https://api.example.com/data");\n' +
+    '  if (response.ok) console.log(response.data);\n\n' +
+    'Make sure your domain is declared in manifest.json:\n' +
+    '  "permissions": { "network": { "domains": ["api.example.com"] } }';
+
+  // Blocked fetch function
+  function blockedFetch() {
+    console.error(BLOCKED_MESSAGE);
+    return Promise.reject(new Error(BLOCKED_MESSAGE));
+  }
+
+  // Blocked XMLHttpRequest class
+  class BlockedXMLHttpRequest {
+    constructor() {
+      console.error(BLOCKED_MESSAGE);
+      throw new Error(BLOCKED_MESSAGE);
+    }
+  }
+
+  // Make BlockedXMLHttpRequest look like the real XMLHttpRequest
+  Object.defineProperties(BlockedXMLHttpRequest, {
+    UNSENT: { value: 0 },
+    OPENED: { value: 1 },
+    HEADERS_RECEIVED: { value: 2 },
+    LOADING: { value: 3 },
+    DONE: { value: 4 },
+  });
+
+  // ============================================================================
+  // STEP 3: Replace global APIs with blocked versions
+  // ============================================================================
+
+  // Override fetch - make it non-configurable to prevent bypass attempts
+  Object.defineProperty(window, 'fetch', {
+    value: blockedFetch,
+    writable: false,
+    configurable: false,
+    enumerable: true
+  });
+
+  // Override XMLHttpRequest - make it non-configurable
+  Object.defineProperty(window, 'XMLHttpRequest', {
+    value: BlockedXMLHttpRequest,
+    writable: false,
+    configurable: false,
+    enumerable: true
+  });
+
+  // ============================================================================
+  // STEP 4: Also block in common bypass locations
+  // ============================================================================
+
+  // Block on globalThis (modern JS)
+  if (typeof globalThis !== 'undefined' && globalThis !== window) {
+    try {
+      Object.defineProperty(globalThis, 'fetch', {
+        value: blockedFetch,
+        writable: false,
+        configurable: false
+      });
+      Object.defineProperty(globalThis, 'XMLHttpRequest', {
+        value: BlockedXMLHttpRequest,
+        writable: false,
+        configurable: false
+      });
+    } catch (e) {
+      // Ignore if already defined
+    }
+  }
+
+  // Prevent restoration via prototype manipulation
+  try {
+    Object.freeze(Object.getPrototypeOf(blockedFetch));
+  } catch (e) {
+    // Ignore
+  }
+
+  // ============================================================================
+  // STEP 5: Block EventSource and WebSocket (optional - for future)
+  // ============================================================================
+
+  // EventSource (Server-Sent Events)
+  const BlockedEventSource = function() {
+    console.error('[MyWallpaper Security] EventSource is blocked. Use MyWallpaper.network.fetch() for data.');
+    throw new Error('EventSource is blocked for security. Use MyWallpaper.network.fetch()');
+  };
+
+  Object.defineProperty(window, 'EventSource', {
+    value: BlockedEventSource,
+    writable: false,
+    configurable: false,
+    enumerable: true
+  });
+
+  // WebSocket - block with helpful message
+  const OriginalWebSocket = window.WebSocket;
+  const BlockedWebSocket = function() {
+    console.error('[MyWallpaper Security] WebSocket is blocked. Real-time features are not supported in addons.');
+    throw new Error('WebSocket is blocked for security in addons');
+  };
+
+  // Copy static properties
+  if (OriginalWebSocket) {
+    BlockedWebSocket.CONNECTING = 0;
+    BlockedWebSocket.OPEN = 1;
+    BlockedWebSocket.CLOSING = 2;
+    BlockedWebSocket.CLOSED = 3;
+  }
+
+  Object.defineProperty(window, 'WebSocket', {
+    value: BlockedWebSocket,
+    writable: false,
+    configurable: false,
+    enumerable: true
+  });
+
+  // ============================================================================
+  // STEP 6: Log security initialization
+  // ============================================================================
+
+  console.warn('[MyWallpaper Security] Network sandbox active. Use MyWallpaper.network.fetch() for network requests.');
+})();