This spec is for review only! This specification is for review and not for implementation! For the latest updates, including important bug fixes, please look at the draft instead.

This specification defines the app: URL scheme.

The app: URL scheme can be used by packaged applications to obtain resources that are inside a container. These resources can then be used with web platform features that accept URLs.

This specification is currently in the "last call" phase at the W3C. A list of changes that have been made during this period is available on GitHub.

Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

app: URL

An app: URL is a [[!URL]] that can be used by a packaged application to address resources within its container (e.g., a .zip file).

Instance identifier

The instance identifier is a string that uniquely identifies an instance of a packaged application. It serves the role of the authority component in a URI.

When the instance identifier is not provided by the developer, a user agent MUST synthesize one. The structure and length of identifier represented is application specific, but it MUST be suitable to use along with the app: scheme as a Document's [[!ORIGIN]]. See also privacy and security considerations.

Privacy Considerations

Using unique identifiers (e.g., a UUID) as an instance identifier can be exploited by an adversary as a digital finger print. This can allow a developer to, for example, restore cookies even if the user has cleared cookies from a user agent. As such, if the user agent relies on unique identifiers as the host component, then it should provide end-users with a means of regenerating the authority component. For instance, A user agent can the regenerate the instance identifier when the user clears the user agent's private data.

Fetching a resource from a container

To fetch a resource using the app: URL using a request request:

  1. If request's method is not `GET`, or if origin does not match the instance identifier for this application, return a network error.
  2. Let path be the path of URL.
  3. Let response be a response.
  4. If attempting to access the resource at path results in an error (e.g., not found, the file is corrupt, locked, etc.), return a network error and terminate this algorithm.
  5. If request includes a `Range` header:
    1. If the value of the `Range` header is a valid byte range [[!HTTP11]]:
      1. Set response body to be the data from path at the start and end of `Range`.
      2. Set response status to 206.
  6. Otherwise, set the response body to be the data at path.
  7. Set the response headers:
    1. `Content-Length`, computed as per [[!HTTP11]].
    2. `Content-Type`, the MIME type of the resource at path computed as per [[!SNIFF]].
  8. Return response.

Security considerations

When fetching data from an app: URL, a user agent needs to make sure that only files that were in the container can be accessed (i.e., those files should be sand-boxed). User agents need to watch out for symbolic links (or similar) inside a container, which can attempt to trick the user agent into accessing files that are on other parts of the file system.

There is one class of product that can claim conformance to this specification: a user agent.

A user agent is an implementation of this specification.

Use Cases

For developers, this specification attempts to address the following use cases:

  1. Provide a URL scheme that is compatible with the features and security model of [[HTML]], so that applications that are packaged can make full use of web platform's capabilities. For example, the app: URL scheme should be usable as a document's address so that it can serve as its origin, and it should be compatible with APIs like [[XHR]].
  2. Provide fetching model that constrains retrieval of files to a specific container.
  3. Provide an addressing scheme that is easy to work with - and that developers are already accustomed to working with. The developer should not be bothered as to whether they are using http:// or app:// - the Web's capabilities and APIs need to just work!
  4. Support the ability to playback audio and video files within a packaged web application, including the ability to seek without needing to load the full resource.

Examples

The following example shows the results of using "app://com.foo.bar/index.html#example" as the document's location.

<!doctype html>
<script>
//Example using HTML's Location object
var loc =  window.location; 
console.log(loc.protocol === "app:"); //true 
console.log(loc.host === "com.foo.bar"); //true 
console.log(loc.href === "app://com.foo.bar/index.html"); //true 
console.log(loc.origin === "app://com.foo.bar"); //true 
console.log(loc.pathname === "/index.html"); //true 
console.log(loc.hash === "#example"); //true 
console.log(loc.port === ""); //true
</script>

This example shows an app: URL being resolved in [[HTML]]. In this case, document's location is "app://c13c6f30/index.htm". The random string "c13c6f30" serves as the instance identifier.

var img = document.createElement("img");

//the following setter triggers HTML's resolve algorithm 
img.src = "example.gif"; 

//and the expected output: 
console.log(img.src === "app://c13c6f30/example.gif") //true

//Append the image to the document
document.body.appendChild(img); 
</script>

This example shows a resource within a packaged application being retrieved over [[XHR]].

function process(text) {
  // process the resulting data 
}

var xhr = new XMLHttpRequest();
xhr.onload = () => process(this.responseText);
xhr.open( "GET", "playlist.json");
xhr.send();

This example shows how an app: URL can be used in conjunction with a HTTP `Range` header to request a range of bytes from a file inside a package.

var url = "sample.mp3"; 
var xhr = new XMLHttpRequest(); 
xhr.open('GET', url, true); 
xhr.responseType = "arraybuffer"; 
xhr.setRequestHeader('Range', 'bytes=100-199'); 
xhr.send(); 
console.log(Uint8Array(xhr.response).byteLength === 100);// true

Acknowledgments

The bulk of the text in this specifications was derived from the Widget URI scheme specification. The Systems Application working group acknowledge the hard work of the Web Applications Working Group in laying down the foundations for this specification.