The app: URI scheme
Editor's Draft- Last updated 22 May 2013
- This Version:
- http://www.w3.org/2012/sysapps/app-uri/
- Git Repo:
- https://github.com/sysapps/app-uri
- Version history:
- Github commits
- Bug tracker:
- Issue tracker on github
This specification defines the app: URI scheme and rules for
dereferencing an app: URI, which can be used to address
resources inside a package (e.g., a packaged application). The
dereferencing model relies on HTTP semantics to return resources in a
manner akin to a HTTP GET request. Doing so allows this URI
scheme to be used with other technologies that rely on HTTP responses to
function as intended, such as [XHR].
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
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.
This is the First Public Working Draft of The app: URI scheme specification. This document was produced by the System Applications Working Group. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All feedback is welcome.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
HTML applications that run locally on a file system have traditionally relied on the file URL scheme of [RFC1738] as a document's address. Although usable in a great deal of cases, relying on the file URL scheme has several serious drawbacks:
Lack of HTTP response semantics: meaning that it is not possible to use, for instance, [XHR] to retrieve resources from within a package.
Security/privacy issues: on Unix systems, naive implementations expose the username as part of the path, as well as the full path on the file system to where a file is residing (e.g., "/Users/username/app/index.html"). In addition, the file URL scheme potentially opens up the ability for an attacker to address any file on the file system.
As stated by [RFC1738]:
The file URL scheme is unusual in that it does not specify an Internet protocol or access method for such files; as such, its utility in network protocols between hosts is limited.
To overcome the above limitations of the file: URL scheme, this specification
standardizes the app: URI scheme and
rules for dereferencing an
app: URI. As a replacement technology for the file URL scheme, the app: URIs serve
a number of functions:
An app: URI is a safer alternative to the file URL scheme, as it does not allow
addressing outside a sand-boxed environment. Additionally, it does
not expose the location of a file on user's local device, nor their
username, as in the case with some Unix-based implementations.
An app: URI can serve as a
document's address, which can serve as the origin
for [HTML] or [SVG]
applications. This enables the use of many features that rely on the
same-origin
policy (e.g., [WebStorage]) and allows
a user agent to resolve
the attribute values of certain DOM elements (e.g., the
img element's src attribute).
app: URI provides a means to retrieve a file from
within a package using similar semantics to performing a GET
request over [HTTP]. This allows the
app: URI scheme to be used with other technologies that rely
on HTTP responses, such as [XHR]. It also allows the
DOM elements to respond accordingly based on how resources are loaded or
if a HTTP-like error occurs (e.g., firing an event when a resource is not
found, or access is denied for security reasons).
This section is non-normative.
|
|
 running instance |
app://c13c...6f30/index.html
|
app: URI.
Using then app: URI above, the following example shows
[HTML]'s window.location using then app: URI.
<!doctype html> <script> //Example using HTML's Location object var loc = window.location; console.log(loc.protocol === "app:"); //true console.log(loc.host === "c13c6f30-ce25-11e0-9572-0800200c9a66"); //true console.log(loc.href === "app://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html"); //true console.log(loc.origin === "app://c13c6f30-ce25-11e0-9572-0800200c9a66"); //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: URI being
resolved
in [HTML].
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-ce25-11e0-9572-0800200c9a66/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() {
// process the resulting data
}
var xhr = new XMLHttpRequest();
xhr.onload = (hxr) => process (xhr.responseText);
xhr.open( "GET", "playlist.json");
xhr.send();
Everything in this specification is normative except for sections explicitly marked as non-normative, examples, and notes.
The key words must, should, recommended, and optional in this specification are to be interpreted as described in [RFC2119].
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 that is able to synthesize app: URIs as well as dereference them.
A package is the logical container that
contains the files being addressed via the app: uri scheme.
An app: URI is a string that
conforms to the production of the following [ABNF]:
appuri = scheme "://" authority path [ "?" query ] [ "#" fragment ] scheme = "app" authority = 1*unreserved / uuidWhere
path, query,
fragment,
and unreserved
are defined in [IRI]. And, and uuid is
defined in [UUID]. See Synthesizing an app:
URI for more information on the use of UUID in construction of the
authority field.
app: URI
When synthesizing an app: URI, a user agent MUST generate a string
that conforms to appuri, and normalize
it using syntax-based
normalization as defined in [IRI].
The authority is a unique identifier that
represents the instance of a software application that is making use of
then app: URI (e.g., in the case of a packaged application,
it represents an instance of an application).
How long the identifier represented by the authority is bound to an instance of an application is application specific (e.g., it may be reset when the user clears the user agent's private data, or can last until the application is uninstalled from an end-user's device). See privacy and security considerations.
The reason for having a unique authority is, amongst other things, to prevent multiple instances from overriding each other's data.
It is recommended that a [UUID] be used as the value of the authority component (but it's not mandatory! Other types of authorities, like reverse domain name notation, are allowed). Using a [UUID] makes it improbable that two URIs will be alike, and also makes them hard to guess.
The query and
fragment
components, when present, complement the path component in
identifying a resource within a package [URL]. However, when
dereferencing, the
query and fragment components don't play any part in
locating a file inside of package.
For example, the following app: URIs all return the same
file (example.gif):
app://c1..66/example.gif?hello
app://c1..66/example.gif?hello=foo&bar=baz
app://c1..66/example.gif?hello#hi-there
This section describes how a user agent retrieves files from inside a
container by dereferencing an app: URI, and how a user agent handles error conditions (e.g., when a
file is not found). The purpose of this dereferencing model is to make
retrieval of files from a container "look and feel" like a HTTP request
(except the request and response are performed over "app://"
instead of "http://").
For simplicity, this specification does not define any means for cache control for content inside a container (e.g., dealing with e-tags). However, a user agent MAY implement [HTTP] cache controls if they so desire.
A response means a HTTP response and can include any HTTP response fields (e.g., the name of the user agent as the Server:) and any entity header fields the user agent deems will be helpful to a developer (e.g., Content-Length, Last-Modified, Date, Content-Encoding, Content-MD5). In the case of an error in the request (i.e., status codes 500, 501, 400, 404), the user agent MUST return an empty response body. Optionally, in case of an error in the request, the user agent SHOULD provide the developer with feedback indicating what error occurred (e.g., in an error console or where network request information is available via the user agent's developer tools).
To dereference a app: URI to a file in a app
package a user agent MUST
apply the rules for
dereferencing an app: URI.
Note: A user agent can deference a URI scheme using other means/technologies (e.g., a proxy or local web server), but the end result needs to be indistinguishable from the result that would be obtained by following the specification.
The rules for dereferencing
an app: URI are as follows:
If the request is not a [HTTP] GET request, return a [HTTP] 501 Not Implemented response and terminate this algorithm.
Ignore any [HTTP] request headers.
Let URI be the value of the [HTTP] Request URI.
Resolve URI into an absolute URL using the document's origin as the base.
If the URI does not conform to the appuri ABNF, return a [HTTP]
400
Bad Request response and terminate this
algorithm.
If the URI uses the scheme 'app', but the
authority does not match the one
assigned to this document, return a [HTTP]
403
Forbidden response and terminate this
algorithm (i.e., prevent inter-application content access).
Let potential-file be the result of attempting locate the file at path.
If potential-file is not found at the given path inside the container, return a [HTTP] 404 Not Found response.
Otherwise, if retrieving potential-file results in an error (e.g., the file is corrupt, locked, etc.), return a [HTTP] 500 Internal Server Error response.
Let content-type be the result of applying [SNIFF] to determine the content-type.
Return a [HTTP] 200 OK response, with the value of content-type as the [HTTP] Content-Type header, and with the contents of potential-file as the response body.
This section is non-normative.
Because [UUID]s used by the app: URI scheme are effectively a digital finger print, an application developer could use a UUID to personally identify a user. This can allow a developer to, for example, restore cookies even if the user has cleared cookies from a user agent. As such, user agents should provide end-users with a means of regenerating the authority component of an app: URI. For example, the UUID for an application could be regenerated every time the application is started. Or the UUID could be regenerated when the user clears private data from the user agent.
When dereferencing an app: URI, a user agent needs to make
sure that only files that were in the package can be accessed (i.e.,
those files should be sand-boxed). User agents need to watch out for
symbolic links
(or similar) inside a package, which can attempt to trick the user agent
into accessing files that are on other parts of the file system.
As this specification relies on the standardized heuristics for determining the content type of files defined in the [SNIFF] specification, implementors need to consider the security considerations discussed in the [SNIFF] specification.
For developers, this specification attempts to address the following use cases:
Provide a URI scheme that is compatible with the features and
security model of [HTML], so that applications that are packaged can
make full use of [HTML]'s capabilities and those
of related technologies. For example, the app: uri
scheme should be usable as a
document's address so that it can serve as its origin,
and it should be compatible with APIs that rely on [HTTP] responses, like [XHR].
Provide a URI scheme that is secure, in that it is constrained to just resources within a package.
http:// or app:// - the Web's
capabilities and APIs need to just work!
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.
Thanks also to Robin Berjon, who helped edit this specification when it was part of WebApps.
Graphic icons used some examples of this specification were created by Ömer ÇETİN and are available for use under a Creative Commons Attribution 3.0 license.