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/.
This document defines a URI scheme for addressing resources within a packaged web application.
This document was published by the System Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All feedback is welcome.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
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: URIWhen 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?helloapp://c1..66/example.gif?hello=foo&bar=bazapp://c1..66/example.gif?hello#hi-thereThis 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 MAY include a message describing the error in the [HTTP] response body.
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.