WebAPI/WidgetAPI

Goals

The widget API allows privileged application have ability to embed other applications in their own iframe, e.g. homescreen, lockscreen ....etc.

Proposal

extend manifest.webapp

An application exposes its widget view via declaring details of widget in mainfest.

 {
   name: "MyApp2000",
   ...
   widgets: {
     "mywidget1": {
       "name": "MyApp2000 Widget",
       "href": "/widget.html",
       "description": "This is my cool widget",
       "screenshot": "foo.jpg"
      },
     "myotherwidget": { ... }
   }
   widgetPages: [
     "/widget.html",
     "/news_reader_settings.html",
     "/some_other_page.html"
   ]
   "locales": {
     "en-US": {
       "name" : "MyApp2000",
       "discription":"Cool App",
       "widgets": {
         "mywidget1": {
           "name":"MyApp2000 Widget",
           "description":"This is my cool widget",
           "screenshot": "foo_en-US.jpg"
         },
          "myotherwidget": { ... }
       }
     }
   }
 }

embed-widgets bug 1005818

In order to expose to privileged APPs and consider security issue.

• "embed-widgets" is a new permission for "mozwidget" attribute, it is similar to 'embed-apps' but is more restricted. Please refer to next section.
• Set manifest entry in "widget" attribute.

 <iframe mozbrowser=“true" mozwidget="manifestURL" src=“widget.html” remote=“true”> 

permission requirements

• embed-widgets
• homescreen-webapp-manage (bug 899994, bug 1000313)
• browser-api (combine with embed-widget would be downgrade )

Restriction

• Limite SRC value in widgetPages list.
• Disallow parts of security sensitive browser API
• Ignore mozLockOrientation/mozUnlockOrientation

examples

• APP:

 <iframe mozbrowser=“true" mozapp=“manifestURL” remote=“true” src=“appURL”>

• Widget:

 <iframe mozbrowser=“true" mozwidget=“manifestURL” remote=“true” src=”widgetURL”> 

• Open Bookmark:

 //browser (full-set)
 <iframe mozbrowser=“true" remote="true" src="http://example.com">

Pages DON'T Want to Be Shown in Widgets

Packaged App

An app can use "widgetPages" to list the white list of widget pages. All pages in this list can be accessed through widget iframe. Others are shown as blank page.

• If a widget navigates to pages which are not listed in widgetPages, the widget iframe shows blank on it.
• If a widget navigates to another domain, the widget iframe cannot use any APIs which requires permissions.

Web Pages

A web page can declare itself to not be embedded in widget iframe by "X-Frame-Options", like normal web page. For more options of X-Frame-Options can be found at: https://developer.mozilla.org/en-US/docs/Web/HTTP/X-Frame-Options

Localization of Widget Info

Similar to app's localization, the localization of widget info MUST be embedded in "widgets" of "locales" properties. And they are referenced to each other with widget id, like mywidget1 or myotherwidget.

Issues under discussion

Browser API

Need to clarify which methods/Events are safe or unsafe.

Not security sensitive

• Performance methods
  • setVisible()
  • getVisible()

• Event methods
  • addNextPaintListener()
  • removeNextPaintListener()

• Events
  • mozbrowserasyncscroll
  • mozbrowserclose
  • mozbrowsererror
  • mozbrowserloadend
  • mozbrowserloadstart

Security sensitive

• Event methods
  • sendMouseEvent() - cross-origin interaction, can cause unexpected actions in web apps
  • sendTouchEvent() - cross-origin interaction, can cause unexpected actions in web apps

• getScreenshot()

• Events
  • mozbrowserusernameandpasswordrequired - leaks host and realm
  • mozbrowseropenwindow (i.e. window.open)
  • mozbrowsershowmodalprompt (i.e. alert(), confirm(), prompt())
  • mozbrowsercontextmenu
  • mozbrowsersecuritychange - can tell is page is https or not
  • mozbrowserlocationchange - discloses URL (can contain secrets)
  • mozbrowsericonchange - discloses the icon URL. Might be a privacy issue.
  • mozbrowsertitlechange - discloses title, privacy issue.
  • mozbrowseropensearch - I assume this discloses the link value, maybe a privacy issue?

no use case

• Navigation methods
  • reload()
  • stop()
  • getCanGoBack()
  • goBack()
  • getCanGoForward()
  • goForward()
• Performance methods
  • purgeHistory()

Q&A

• Why we need an app to explicitly expose its widget view? Is there any use case that an app doesn't want to be opened as a widget?
  • The app thinks its function can't be performed in widget mode, like lockscreen app or camera app.
  • Just doesn't want itself to be embeded by other apps for various concerns, like Facebook app or bank apps.

• Is it possible to navigate to an external link within a widget?
  • It should be fine to navigate an external link within a widget because window.location is changed by widget itself under its window context, not caused by the widget embedder.
  • A widget is also an iframe. It follows "X-Frame-Options" restrictions. If a web page declare X-Frame-Options, the widget cannot shows that page.

• May a widget request to enlarge itself to full screen as its app mode?
  • No, we don't have a better idea for this case now. Issues like how to force homescreen app to deal with the the resize event requested by widget, how to update mozbrowser iframe attributes to indicate the frame is in app mode...

• Some apps want to app.launch() its app mode while user click its widget, but some want to be enlarged. Is there a way to specify?
  • We may introduce an attribute in manifest which tells widget embedder how to process the enlarging behavior. But we have to discuss it with Web API team.

Bugs

• bug 1005818 A new 'embed-widgets' permission exposing to privileged apps for solving widget case.
  • Part1: Add permission "embed-widgets" and HTMLIFrameElement attribute "mozWidget"
  • Part2: Implementation of checking if a window is able to embed a specific widget.
  • Part3: Enable to embed a widget if preconditions hold
  • Part4: Only limited browser API are available to a widget