index.bs

<pre class='metadata'>
Title: Web User Agents
Shortname: web-user-agents
Level: none
Status: NOTE-ED
Group: tag
Repository: w3ctag/user-agents
URL: https://w3ctag.github.io/user-agents
TR: https://www.w3.org/TR/web-user-agents/
Editor: Jeffrey Yasskin, w3cid 72192, Google https://google.com, jyasskin@google.com
Editor: Sarven Capadisli, w3cid 46140, Invited Expert, https://csarven.ca/
Complain About: accidental-2119 yes, missing-example-ids yes, mixed-indents no
Markup Shorthands: markdown yes, css no
Assume Explicit For: yes
Boilerplate: conformance no
Abstract: Web user agents include both web browsers and other intermediaries
    between end-users and the web.
    Each user agent serves its user,
    not any of the other constituencies.
    A user agent owes its user various duties,
    which should be established through collective discussions
    and embodied in the various standards that user agents implement.

</pre>

# Audience # {#audience}

This document is intended for:

* **Technical authors** who want to reuse or reference these concepts in their own specifications or documentation.
* **User agent developers** who want to align implementations with design and privacy principles that prioritize their users.
* **Web developers** who want to understand why user agents prioritize user privacy and security over other constituencies, including developer convenience.
* **Regulators and policymakers** who seek to understand the duties, principles, and expectations guiding user agent behavior.

# What is a web user agent # {#what}

A <dfn lt="general user agent">user agent</dfn>, in general, is any software entity
that interacts with other entities on behalf of its user.
User agents include many operating systems; email clients; PDF, ebook, and image viewers;
[=credential managers=], including digital wallets; and many other kinds of software.

<!-- TODO: Export this once it can replace the Infra definition. -->
A <dfn lt="user agent|web user agent" noexport>web user agent</dfn> is
any software entity that interacts with websites outside the entity itself,
on behalf of its user,
including simply rendering the content of websites or performing actions requested or authorized by the user.
In web specifications and the rest of this document,
web user agents are usually referred to as just "[=user agents=]".
Either fully-qualified term can be used
if there's a chance of confusion.
A person can use many different user agents in their day-to-day life.

The most common type of web user agent is the web browser,
including in-app browsers that can follow cross-site links.
However, user agents also include other tools like
search engines, voice-driven assistants, and generative AI systems
that present snippets or summaries of website content,
help people navigate and interact with websites,
or perform automated actions on the user’s behalf.

User agent behavior is not completely defined by web standards
or even by technical specifications in general.
In particular,
user agents choose which specifications to implement in order to best serve their users,
and they implement proprietary user interfaces and other behavior
around the specifications they do implement.

## User agents as software components ## {#ua-as-software}

As software components, user agents can be parts of larger applications
and can call libraries that implement the web platform or parts of it.

When an application makes a clear distinction
between its pieces that are [=user agents=] and its pieces that aren't,
then only the [=user agent=] parts,
which browse content from outside the user agent itself,
need to follow the [=user agent duties=].
Parts that are clearly only showing the application's own content
can act on their own behalf,
but the application should still
give its users clear expectations about
what behavior they should expect from different parts of the application.
If the distinction between internal and external content is too small—for example
if the application doesn't show an address bar
or another indicator of content origin
when browsing external content—then
the application should also follow the [=user agent duties=]
when showing its own content.

Similarly a library that implements the web platform
may or may not be a full [=user agent=].
Some, like [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller)
and [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs)
take on the responsibility of implementing the [=user agent duties=]
and of clearly distinguishing between the external content they browse
and the content controlled by the embedding application.
These libraries are [=user agents=].

Other libraries, like the
[Android](https://developer.android.com/reference/android/webkit/WebView),
[iOS](https://developer.apple.com/documentation/webkit/wkwebview),
and [Windows](https://developer.microsoft.com/en-us/Microsoft-edge/webview2/)
WebView libraries,
are designed to support many kinds of applications.
Because some of these applications include only their own content,
WebView libraries are not meant to be [=user agents=] on their own,
and they do not implement the [=user agent duties=].

Ultimately, an embedding application is responsible for
following the [=user agent duties=]
if it, or any part of it, acts as a [=user agent=].
This can be straightforward if the application only browses external content through a [=user agent=] library.
Developers need to take extra care
to follow the [=user agent duties=]
when using a non-[=user agent=] WebView to implement an in-app browser .

# Duties of user agents # {#duties}

Each user agent serves its user ([[!RFC8890 inline]]),
not any of the other constituencies.
A user agent owes its user various
<dfn lt="user agent duties|UA duties">duties</dfn>,
which should be established through collective discussions
and embodied in the various standards that user agents implement.


## Protection ## {#protection}

[[design-principles#safe-to-browse|It should be safe to visit a web page.]]
Visiting a page must not by itself
let the page change the user's computer or environment,
such as by installing software or accessing hardware.

Any data revealed to sites or other observers
should be aligned with the user's preferences
and follow the principle of [[design-principles#data-minimization|data minimization]].
In particular, user agents must act to
limit the potential for sites to track user activity [[unsanctioned-tracking]].

Users may [choose to share more information](https://www.w3.org/TR/privacy-principles/#dfn-opt-in),
such as by filling out forms or granting permissions.
Even then, user agents must help users avoid deception and
clearly signal when a page attempts to gain elevated access.

Access to local files or other sensitive resources
must be limited to clear, intentional user actions, with appropriate warnings.

<div class="example" id="example-protection-exploits" heading="Attacks">

User agents need to prevent malicious code on a site from
being able to escape the user agent
to modify the user’s computer or access other [=origins=].
User agents meet this duty of protection by sandboxing components,
using memory-safe languages,
and employing security teams to find and respond to vulnerabilities.
These defenses need to evolve continuously to address new threats.

</div>

<div class="example" id="example-protection-tracking" heading="Tracking">

If a person visits unrelated websites,
it's feasible to avoid sending a shared identifying cookie to embedded iframes.
A browser that does send such a cookie is failing its duty of protection.
However, revealing a stable IP address is currently unavoidable,
so it's not a violation.

</div>

<div class="example" id="example-protection-local-files" heading="Local Files">

User agents are expected to prevent pages from accessing local files
unless the user explicitly selects or opens one.
This motivates behaviors like:

* giving each `file:` URL its own [=url/origin=],
* removing path components from
    <a element-state for="input" lt="File Upload">`<input type=file>`</a> uploads, and
* restricting which local fonts can be used in <a at-rule>@font-face</a> rules.

However, users can still choose to share files,
e.g., via uploads or downloads.
APIs like [[file-system-access inline]] don’t violate this duty,
provided users have the tools to [[design-principles#user-decisions|make good decisions]].

</div>


## Honesty ## {#honesty}

A user agent must mediate between the Web and its user,
explaining what is happening in a form the user can understand. 
When the user agent performs actions automatically or on behalf of the user, it must clearly communicate those actions and their consequences.

A user agent may use multiple approaches for explanations, including
text, permission prompts, indicators, previews, and other interface elements.
Consider the placement of these elements and whether anything needs emphasis.

A quintessential example is user agents indicating if a website was served over an encrypted connection.
This has evolved over time, from insecure sites being shown with a broken lock icon,
to some user agents explicitly including the text "not secure" in the URL bar.

Specifications, like the [[mediacapture-streams inline]], include
[[mediacapture-streams#privacy-indicator-requirements|Privacy Indicator Requirements]]
that require user agents to explain some specific kinds of website behavior,
but user agents should also use the same techniques when users need to know
about other behavior, even if a specification doesn't specifically call out that behavior.

An honest user agent actively works to present the truth to its user.
It doesn't just avoid lies.
Its explanations
should clearly represent the current state and likely consequences,
avoid euphemism or ambiguity,
and make it obvious when sensitive activity is occurring.

The user agent should choose when and how often to show these explanations,
so explanations arrive when helpful and inform rather than distract.
The user agent should ensure the user can control if and when they make a decision.

For example, if a website is using a long-lived permission like geolocation or audio recording, 
the user agent can explain what's happening by showing an indicator icon in the URL bar.

## Loyalty ## {#loyalty}

A user agent must serve its user's interests
over its implementer's interests
and over the interests of any other party.

A user agent can be loyal
while also collecting payment for its services,
as long as that payment is fair and was agreed ahead of time.

A user agent can also help its user
make a credible commitment to a page in order to get that page's services,
and it's not disloyal to maintain that commitment after getting the services.

A user agent must not obstruct its users from switching to another user agent.
For example, it must not block access to, export, or store user data in ways that prevent portability.
This includes identity information, bookmarks, history, passwords, and credentials such as passkeys.
If the user agent relies on the underlying <abbr title="Operating System">OS</abbr> to store credentials,
there needs to be a way for users to allow other user agents to access those credentials.

<section class="non-normative">

# Acknowledgements # {#acknowledgements}

Thanks to the [[Infra inline]]
for an earlier definition of User Agents
and to [[privacy-principles inline]] for the initial version of these duties.

</section>