Runtime Model for System Application

Editor's Draft 20 June 2012

This Version:
Send feedback to public-sysapps@w3.org (archives)

Table of Contents

  1. 1 Conformance
    1. 1.1 Dependencies
  2. 2 Design Principles
  3. 3 Application Lifecycle
    1. 3.1 Installation
    2. 3.2 Event Page
    3. 3.3 Launch
    4. 3.4 Event-initiated startup
    5. 3.5 Creating Windows
    6. 3.6 Termination
    7. 3.7 Update
    8. 3.8 Uninstallation
  4. 4 Conventions
  5. 5 Differences from the Web Platform
    1. 5.1 Differences
    2. 5.2 Disabled Features
  6. References
  7. Acknowledgments

1 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

1.1 Dependencies

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

Some of the terms used in this specification are defined in Web IDL. [WEBIDL]

2 Design Principles

The runtime has the following core design principles:

The user (or a trusted delegate) must make a trust decision to decide to install a System Application before it can be used.
It must not be possible to create persistent malware with System Applications.
Offline first
System Applications should run offline and should display a reasonable user interface without any explicit effort by the developer. They should be able to automatically recover from lost or intermittent connectivity. They don't need to provide their full functionality when offline, but they should not be obviously or irrecoverably broken.
Outside of the browser
The runtime launches System Applications outside of the browser and should not provide traditional browser "chrome" such as back/forward navigation buttons or a location bar.
The runtime provides System Applications with APIs that are inherently dangerous and have potential privacy and security ramifications. The runtime must provide a trust mechanism whereby either the user explicitly chooses to trust a potentially dangerous application or a third party vouches for the safety of the application.
The APIs provided by the runtime are segmented according to a number of fine-grained permissions. If an application has not been granted a permission, the runtime must prevent the application from using the associated APIs. Developers should minimize the permission they request for their applications.
System applications must be isolated from other applications and the underlying operating system except for via explicitly defined, narrow, typed, mediated APIs.
The runtime must be resistant to vulnerabilities that could lead to remote security exploits. For example, the runtime should make it difficult for attackers to mount a cross-site scripting attack against System Applications.
A System Application must be prepared to be terminated at any moment without notification. The application should be able to restore itself to its previous state quickly and easily. The runtime must prevent a system application from delaying, prompting or canceling the application's termination.
A third party (such as a broker, store, or market) must be able to verify the code of a System Application and all of the future updates that the third party delivers to the user. Unverified code may be permitted, but such code must be sandboxed and must not receive privileges for dangerous APIs.
A third party (such as a broker, store, or market) must be able to revoke and disable a System Application that the third party provided to the users, even after the user has installed the application.

3 Application Lifecycle

3.1 Installation

System Applications must define the complete set of permissions or capabilities that they require or might request at runtime. This list is set at install time and must not be changed until the application is updated. Applications must be installed before they can be run with these permissions. This installation acts as a trust gesture and may be initiated either by the user or by a trusted delegate (e.g. operating system, device maker, device distributor, or enterprise policy). User-initiated installation should include a confirmation step to mitigate the risk that a vulnerability in the runtime might cause automatic installation.

This document does not impose requirements on what information, of any, should be presented as part of the installation experience. It is up to the runtime vendor to determine how best to assess the trust level and risk level of an application and how or if to convey that information to the user. In its simplest form, a confirmation might simply be an install button in some protected part of the runtime user interface. A more typical install experience might present an "are you sure?" confirmation dialog that summarizes the permissions requested by the application.

3.2 Event Page

During installation, the application must define an event page. The event page is a resource within the application similar to other resources but with a few important differences:

  1. When running the event page, the runtime must not display display the event page to the user. Instead, the page runs in the background.
  2. The event page is a singleton: there must be exactly one event page per application.
  3. The runtime may close the event page in certain circumstances. When an event page is not executing any script, has no pending callbacks, and no open windows, the runtime should close the event page. In addition, the runtime may close the event page in order to reduce resource consumption.

3.3 Launch

When the user initiates application startup, the runtime launches the application by running these steps:

  1. Instantiate the application's event page.
  2. Spin the event loop until the event page's DOMContentLoaded event finishes firing. FIXME: Is this correct?
  3. Queue a task to Fire an event named launch at the event page's window object.

Notice that the runtime does not create any visible windows when launching an application. The application can choose whether to display any visible windows when handling the launch event.

3.4 Event-initiated startup

The runtime may start the application for the purpose of delivering events from the system. For example, a system-level service might ask an email application to send an email on its behalf. To handle these causes, the runtime launches the application in the background to handle an event event by running these steps:

  1. If the application's event page is not currently instantiated:
    1. Instantiate the application's event page.
    2. Spin the event loop until the event page's DOMContentLoaded event finishes firing. FIXME: Is this correct?
  2. Queue a task to Fire event at the event page's window object.

The runtime should not indicate that applications launched are running in the runtime's primary user interface. For example, the application should not appear in the operating system's task switcher. The runtime may indicate that applications launched in this way are running in secondary user interface elements, such as a task manager or battery profiler.

Applications launched in this way can run for extended periods of time without being visible, for example, if they receive events frequently. Typically, applications should handle these events quickly and consume a minimal amount of resources when running in the background.

3.5 Creating Windows

An event page may create one or more windows. By default, these windows are created with a script connection to the event page and are directly scriptable by the event page. FIXME: Do we want to specify an interface for creating an managing windows in this document?

3.6 Termination

The application can terminate in a number of situations:

When an application is terminated, the runtime must close all of the application's pages, including the event page and any visible pages. The runtime must not let the application show down or cancel termination, including prompting the user. Applications should automatically save their state periodically to protect against data loss.

The runtime should avoid terminating the active, focused application if at all possible. However, the runtime may terminate that application as a last resort (e.g., due to resource exhaustion or bad behavior).

3.7 Update

The runtime may update applications whenever the application's event page is not instantiated. When launched, the runtime must use the latest installed version of the application.

When updating, an application may request a change in its set of permissions. The runtime may require a trust gesture from the user to approve these changes.

3.8 Uninstallation

The runtime must let the user uninstall applications. If the application is running when uninstalled, the runtime must terminate the application. After uninstallation, there should be no code executing or private data stored by the runtime.

Uninstallation can lead to data loss because the runtime terminates the application without warning and deletes the application's private data. The runtime should warn the user about these hazards before uninstalling the application.

The runtime must prevent applications from persisting itself or a derived application after being uninstalled. This requirement helps protect the user from persistent malware.

4 Conventions

Functions must not block the main thread of the application. If the function can execute using cached in-memory or computed values, the function may return values syncronously or throw exceptions.

In other cases, functions must be asynchronous. Asynchronous functions must have no return value, throw no exceptions, and the last argument of the function should be a callback. The callback must be called exactly once when the function execution has completed, whether or not the function completes successfully or generates data.

Typically, callbacks will take an error object as their first argument. If the function does not complete successfully, the error argument will be non-null. Otherwise, the error argument will be null.

Each functions is associated with one or more privileges. These privileges vary in grainularity, ranging from granting access to entire modules, interfaces, or functions. In some cases, a privilege might grant permission to call a function with a subset of its possible arguments.

The runtime may grant these privileges either when the user installs the application or when the application requests access at runtime (or some combination thereof).

Interfaces should be visible and callable regardless of whether the application has the requisite permission. If the application does not have permission to call a function, the runtime should generate a permission error (FIXME: Citation needed). Applications should be prepared to handle these errors.

Regardless of the level of privilege, applications must be allowed to make irreversible changes to the underlying operating system. For example, For example, applications must not be able write to arbitrary parts of the file system without a specific user action.

Applications must not be able to interfere with other applications. Interaction between apps must be mediated by either explicit communication channels or shared typed storage (such as a MessageChannel or a contacts API).

5 Differences from the Web Platform

The System Applications Runtime is based on the web platform, but has some differences. Some features have been added and some have been removed. Other features are used in the same way but have different behavior behavior differences.

5.1 Differences

Each application must run in single origin [RFC6454], separate from the origins used by other applications and web sites.

Each application must have isolated storage, a separate copy of each type of persistent storage, including cookies and databases, from other applications and from the browser. For example, if the application makes an HTTP request for https://example.com/ and the example.com server responds with a Set-Cookie header [RFC6265], then subsequent HTTP requests to example.com made by the application will include the cookie, but requests made by other applications, or by the browser, will not include the cookie, even if those requests are for example.com.

The runtime must allow applications to issue XMLHttpRequests to every http and https URI without using Cross-Origin Resource Sharing [CORS]. In particular, cookie should be enabled during these requests, but, due to isolated storage, the cookie jar for each host must be empty when the application is installed.

The runtime calls a callback in the application when the runtime is about to terminate the application. (FIXME: Should this information bein the lifecycle section?) Once the runtime calls this callback, the runtime must hide the application and prevent the appplciation from presenting any user interface elements to the user. After five seconds, the runtime will terminate the application. Applications should use this time to complete their current tasks, but applications should not rely upon this notification to prevent data less because the runtime may terminate the application without notice if necessary. Instead, applications should use this notification to clean up shared resource gracefully, such as disconnecting from remote servers.

The runtime must let applications open multiple windows without explicit user gestures. When opening a window, the opener is given a reference to the window's DOMWindow object. The runtime must provide an API for enumerating all of the application's open windows (FIXME: Spec this API).

5.2 Disabled Features

The runtime must prevent the application from loading remote subresources using mechanisms that do not have a reasonable offline user experience or programmatic error handling. For example, the runtime must prevent the application from loading remote scripts, workers, iframes, images, and style sheets. FIXME: Nail down this list.

The runtime must allow the application to load remove audio and video resource. FIXME: Is this requirement based on some rationale or should we just have a list of what is and is not allowed?

FIXME: Fill out this section.


Cross-Origin Resource Sharing, Anne van Kesteren. W3C.
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
HTTP State Management Mechanism, A. Barth. IETF.
The Web Origin Concept, A. Barth. IETF.
Web IDL, Cameron McCormack. W3C.


Thanks to ??? for their useful comments.