6.5 System state and capabilities

The navigator
attribute of the Window interface must return an
instance of the Navigator interface, which represents
the identity and state of the user agent (the client), and allows
Web pages to register themselves as potential protocol and content
handlers:

Must return either the string "Netscape" or the full name of the browser, e.g. "Mellblom Browsernator".

appVersion

Must return either the string "4.0" or a string representing the version of the browser in detail, e.g. "1.0 (VMS; en-US) Mellblomenator/9000".

platform

Must return either the empty string or a string representing the platform on which the browser is executing, e.g. "MacIntel", "Win32", "FreeBSD i386", "WebTV OS".

userAgent

Must return the string used for the value of the "User-Agent" header in HTTP requests, or the empty string if no such header is ever sent.

Any information in this API that varies from user
to user can be used to profile the user. In fact, if enough such
information is available, a user can actually be uniquely
identified. For this reason, user agent implementors are strongly
urged to include as little information in this API as possible.

The registerProtocolHandler()
method allows Web sites to register themselves as possible handlers
for particular schemes. For example, an online telephone messaging
service could register itself as a handler of the sms:
scheme, so that if the user clicks on such a link, he is given the
opportunity to use that Web site. Analogously, the registerContentHandler()
method allows Web sites to register themselves as possible handlers
for content in a particular MIME type. For example, the
same online telephone messaging service could register itself as a
handler for text/vcard files, so that if the user has
no native application capable of handling vCards, his Web browser
can instead suggest he use that site to view contact information
stored on vCards that he opens. [RFC5724]RFC6350

User agents may, within the constraints described in this
section, do whatever they like when the methods are called. A UA
could, for instance, prompt the user and offer the user the
opportunity to add the site to a shortlist of handlers, or make the
handlers his default, or cancel the request. UAs could provide such
a UI through modal UI or through a non-modal transient notification
interface. UAs could also simply silently collect the information,
providing it only when relevant to the user.

User agents should keep track of which sites have registered
handlers (even if the user has declined such registrations) so that
the user is not repeatedly prompted with the same request.

The arguments to the methods have the following meanings and
corresponding implementation requirements. The requirements that
involve throwing exceptions must be processed in the order given
below, stopping at the first exception thrown. (So the exceptions
for the first argument take precedence over the exceptions for the
second argument.)

A scheme, such as mailto or web+auth.
The scheme must be compared in an ASCII
case-insensitive manner by user agents for the purposes of
comparing with the scheme part of URLs that they consider against
the list of registered handlers.

The scheme value, if it contains a colon
(as in "mailto:"), will never match anything, since
schemes don't contain colons.

A MIME type, such as
model/vnd.flatland.3dml or
application/vnd.google-earth.kml+xml. The MIME
type must be compared in an ASCII
case-insensitive manner by user agents for the purposes of
comparing with MIME types of documents that they consider against
the list of registered handlers.

User agents must compare the given values only to the MIME
type/subtype parts of content types, not to the complete type
including parameters. Thus, if mimeType values
passed to this method include characters such as commas or
whitespace, or include MIME parameters, then the handler being
registered will never be used.

The type is compared to the MIME type
used by the user agent after the sniffing algorithms have
been applied.

To get the escaped version of the absolute URL of
the content in question, the user agent must replace every
character in that absolute URL that doesn't match the
<query> production defined in RFC 3986 by the
percent-encoded form of that character. [RFC3986]

If the user had visited a site at http://example.com/ that made the following
call:

This site could then fetch the chickenkïwi.soup
file and do whatever it is that it does with soup (synthesize it
and ship it to the user, or whatever).

title

A descriptive title of the handler, which the UA might use to
remind the user what the site in question is.

This section does not define how the pages registered by these
methods are used, beyond the requirements on how to process the url value (see above). To some extent, the processing model for navigating across
documents defines some cases where these methods are
relevant, but in general UAs may use this information wherever they
would otherwise consider handing content to native plugins or helper
applications.

UAs must not use registered content handlers to handle content
that was returned as part of a non-GET transaction (or rather, as
part of any non-idempotent transaction), as the remote site would
not be able to fetch the same data.

In addition to the registration methods, there are also methods
for determining if particular handlers have been registered, and for
unregistering handlers.

Returns one of the following strings describing the state of
the handler given by the arguments:

new

Indicates that no attempt has been made to register the given
handler (or that the handler has been unregistered). It would be
appropriate to promote the availability of the handler or to just
automatically register the handler.

registered

Indicates that the given handler has been registered or that
the site is blocked from registering the handler. Trying to
register the handler again would have no effect.

declined

Indicates that the given handler has been offered but was
rejected. Trying to register the handler again may prompt the
user again.

The isProtocolHandlerRegistered()
method must return the handler state string that most
closely describes the current state of the handler described by the
two arguments to the method, where the first argument gives the
scheme and the second gives the string used to build the
URL of the page that will handle the requests.

The first argument must be compared to the schemes for which
custom protocol handlers are registered in an ASCII
case-insensitive manner to find the relevant handlers.

The second argument must be preprocessed as described below, and
if that is successful, must then be matched against the proto-URLs of the relevant handlers to find
the described handler.

The isContentHandlerRegistered()
method must return the handler state string that most
closely describes the current state of the handler described by the
two arguments to the method, where the first argument gives the
MIME type and the second gives the string used to build
the URL of the page that will handle the requests.

The first argument must be compared to the MIME types for which custom content handlers are
registered in an ASCII case-insensitive manner to find
the relevant handlers.

The second argument must be preprocessed as described below, and
if that is successful, must then be matched against the
proto-URLs of the relevant handlers to
find the described handler.

The handler state strings
are the following strings. Each string describes several situations,
as given by the following list.

new

The described handler has never been registered for the given
scheme or type.

The described handler was once registered for the given scheme
or type, but the site has since unregistered it. If the handler
were to be reregistered, the user would be notified accordingly.

The described handler was once registered for the given scheme
or type, but the site has since unregistered it, but the user has
indicated that the site is to be blocked from registering the type
again, so the user agent would ignore further registration attempts.

registered

An attempt was made to register the described handler for the
given scheme or type, but the user has not yet been notified, and
the user agent would ignore further registration attempts. (Maybe
the user agent batches registration requests to display them when
the user requests to be notified about them, and the user has not
yet requested that the user agent notify it of the previous
registration attempt.)

The described handler is registered for the given scheme or
type (maybe, or maybe not, as the default handler).

The described handler is permanently blocked from being
(re)registered. (Maybe the user marked the registration attempt as
spam, or blocked the site for other reasons.)

declined

An attempt was made to register the described handler for the
given scheme or type, but the user has not yet been notified;
however, the user might be notified if another registration attempt
were to be made. (Maybe the last registration attempt was made
while the page was in the background and the user closed the page
without looking at it, and the user agent requires confirmation for
this registration attempt.)

An attempt was made to register the described handler for the
given scheme or type, but the user has not yet responded.

An attempt was made to register the described handler for the
given scheme or type, but the user declined the offer. The user has
not indicated that the handler is to be permanently blocked,
however, so another attempt to register the described handler might
result in the user being prompted again.

The described handler was once registered for the given scheme
or type, but the user has since removed it. The user has not
indicated that the handler is to be permanently blocked, however,
so another attempt to register the described handler might result
in the user being prompted again.

The unregisterProtocolHandler()
method must unregister the handler described by the two arguments to
the method, where the first argument gives the scheme and the second
gives the string used to build the URL of the page that
will handle the requests.

The first argument must be compared to the schemes for which
custom protocol handlers are registered in an ASCII
case-insensitive manner to find the relevant handlers.

The second argument must be preprocessed as described below, and
if that is successful, must then be matched against the proto-URLs of the relevant handlers to find
the described handler.

The unregisterContentHandler()
method must unregister the handler described by the two arguments to
the method, where the first argument gives the MIME
type and the second gives the string used to build the
URL of the page that will handle the requests.

The first argument must be compared to the MIME types for which custom content handlers are
registered in an ASCII case-insensitive manner to find
the relevant handlers.

The second argument must be preprocessed as described below, and
if that is successful, must then be matched against the
proto-URLs of the relevant handlers to
find the described handler.

The second argument of the four methods described above must be
preprocessed as follows:

If the string does not contain the substring "%s", abort these steps. There's no matching
handler.

Return the resulting absolute URL as the result
of preprocessing the argument.

6.5.1.3 Security and privacy

These mechanisms can introduce a number of concerns, in
particular privacy concerns.

Hijacking all Web usage. User agents should not
allow schemes that are key to its normal operation, such as
http or https, to be rerouted through
third-party sites. This would allow a user's activities to be
trivially tracked, and would allow user information, even in secure
connections, to be collected.

Hijacking defaults. It is strongly recommended
that user agents do not automatically change any defaults, as this
could lead the user to send data to remote hosts that the user is
not expecting. New handlers registering themselves should never
automatically cause those sites to be used.

Registration spamming. User agents should
consider the possibility that a site will attempt to register a
large number of handlers, possibly from multiple domains (e.g. by
redirecting through a series of pages each on a different domain,
and each registering a handler for video/mpeg —
analogous practices abusing other Web browser features have been
used by pornography Web sites for many years). User agents should
gracefully handle such hostile attempts, protecting the user.

Misleading titles. User agents should not rely
wholly on the title argument to the methods when
presenting the registered handlers to the user, since sites could
easily lie. For example, a site hostile.example.net
could claim that it was registering the "Cuddly Bear Happy Content
Handler". User agents should therefore use the handler's domain in
any UI along with any title.

Hostile handler metadata. User agents should
protect against typical attacks against strings embedded in their
interface, for example ensuring that markup or escape characters in
such strings are not executed, that null bytes are properly handled,
that over-long strings do not cause crashes or buffer overruns, and
so forth.

Leaking Intranet URLs. The mechanism described
in this section can result in secret Intranet URLs being leaked, in
the following manner:

The user registers a third-party content handler as the default
handler for a content type.

The user then browses his corporate Intranet site and accesses
a document that uses that content type.

The user agent contacts the third party and hands the third
party the URL to the Intranet content.

No actual confidential file data is leaked in this manner, but
the URLs themselves could contain confidential information. For
example, the URL could be
http://www.corp.example.com/upcoming-aquisitions/the-sample-company.egf,
which might tell the third party that Example Corporation is
intending to merge with The Sample Company. Implementors might wish
to consider allowing administrators to disable this feature for
certain subdomains, content types, or schemes.

Leaking credentials. User agents must never send
username or password information in the URLs that are escaped and
included sent to the handler sites. User agents may even avoid
attempting to pass to Web-based handlers the URLs of resources
that are known to require authentication to access, as such sites
would be unable to access the resources in question without
prompting the user for credentials themselves (a practice that would
require the user to know whether to trust the third-party handler, a
decision many users are unable to make or even understand).

6.5.1.4 Sample user interface

This section is non-normative.

A simple implementation of this feature for a desktop Web browser
might work as follows.

In this dialog box, "Kittens at work" is the title of the page
that invoked the method, "http://kittens.example.org/" is the URL of
that page, "application/x-meowmeow" is the string that was passed to
the registerContentHandler()
method as its first argument (mimeType),
"http://kittens.example.org/?show=%s" was the second argument (url), and "Kittens-at-work displayer" was the third
argument (title).

If the user clicks the Cancel button, then nothing further
happens. If the user clicks the "Trust" button, then the handler is
remembered.

When the user then attempts to fetch a URL that uses the
"application/x-meowmeow" MIME type, then it might
display a dialog as follows:

In this dialog, the third option is the one that was primed by
the site registering itself earlier.

If the user does select that option, then the browser, in
accordance with the requirements described in the previous two
sections, will redirect the user to
"http://kittens.example.org/?show=data%3Aapplication/x-meowmeow;base64,S2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%253D".

Values of cookies and items in the Storage objects
of localStorage attributes
can change after calling this method, whence its name.
[WEBSTORAGE]

The yieldForStorageUpdates()
method, when invoked, must, if the storage mutex is
owned by the event loop of the task that resulted in the method being
called, release the storage mutex so that it is once
again free. Otherwise, it must do nothing.

Returns a value based on comparing url to
the URLs of the results pages of the installed search engines.

0

None of the installed search engines match url.

1

One or more installed search engines match url, but none are the user's default search engine.

2

The user's default search engine matches url.

The url is compared to the URLs of the
results pages of the installed search engines using a prefix
match. Only results pages on the same domain as the script that
calls this method are checked.

Another way of exposing search engines using
OpenSearch description documents is using a link
element with the search link
type.

The AddSearchProvider()
method, when invoked, must run the following steps:

Optionally, abort these steps. User agents may implement
the method as a stub method that never does anything, or may
arbitrarily ignore invocations with particular arguments for
security, privacy, or usability reasons.

The IsSearchProviderInstalled()
method, when invoked, must run the following steps:

Optionally, return 0 and abort these steps. User agents may
implement the method as a stub method that never returns a
non-zero value, or may arbitrarily ignore invocations with
particular arguments for security, privacy, or usability
reasons.

If the origin of the entry script
is an opaque identifier (i.e. it has no host component), then
return 0 and abort these steps.

If the longest suffix in the Public Suffix List that matches
the end of host1 is different than the
longest suffix in the Public Suffix List that matches the end of
host2, then return 0 and abort these steps.
[PSL]

If the next domain component of host1 and
host2 after their common suffix are not the
same, then return 0 and abort these steps.

Domain labels must be compared after applying the IDNA ToASCII
algorithm to them, with both the AllowUnassigned and
UseSTD3ASCIIRules flags set, in an ASCII
case-insensitive manner. [RFC3490]

Let search engines be the list of
search engines known by the user agent and made available to the
user by the user agent for which the resulting absolute
URL is a prefix match of the search engine's
URL, if any. For search engines registered using
OpenSearch description documents, the URL of the
search engine corresponds to the URL given in a Url element whose rel
attribute is "results" (the default). [OPENSEARCH]

If search engines is empty, return 0
and abort these steps.

If the user's default search engine (as determined by the
user agent) is one of the search engines in search
engines, then return 2 and abort these steps.