change-password-url.bs

<pre class='metadata'>
Title: A Well-Known URL for Changing Passwords
Shortname: change-password-url
Level: None
Status: ED
Group: WebAppSec
Repository: w3c/webappsec-change-password-url
URL: https://w3c.github.io/webappsec-change-password-url/
TR: https://www.w3.org/TR/change-password-url/
Editor: Ricky Mondello, w3cid 103933, Apple Inc. https://apple.com/, rmondello@apple.com
Editor: Theresa O'Connor, w3cid 40614, Apple Inc. https://apple.com/, hober@apple.com
Abstract: This specification defines a well-known URL that sites can use
 to make their change password forms discoverable by tools. This simple
 affordance provides a way for software to help the user find the way to
 change their password.
Complain About: accidental-2119 true
Markup Shorthands: idl yes, markdown yes
</pre>
<pre class="anchors">
text:Location; type:dfn; spec:rfc7231; url:https://tools.ietf.org/html/rfc7231#section-7.1.2
text:refresh state; type:dfn; spec:html; url: https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-refresh
spec: UTS46; urlPrefix: https://www.unicode.org/reports/tr46/
    type: abstract-op; text: ToUnicode; url: #ToUnicode
spec: RESPONSE-CODE-RELIABILITY; type:dfn; text: test the reliability of an origin's response status codes; url: https://w3c.github.io/webappsec-change-password-url/response-code-reliability.html#test-the-reliability-of-an-origins-response-status-codes
</pre>
<pre class="biblio">
{
    "HTTP-SEMANTICS": {
        "aliasOf": "RFC7231"
    },
    "IDNA": {
        "aliasOf": "UTS46"
    },
    "WELL-KNOWN": {
        "aliasOf": "RFC8615"
    },
    "RESPONSE-CODE-RELIABILITY":
    {
        "authors": ["Ricky Mondello", "Theresa O'Connor"],
        "href": "https://wicg.github.io/change-password-url/response-code-reliability.html",
        "publisher": "WICG",
        "status": "CG-DRAFT",
        "title": "Detecting the reliability of HTTP status codes"
    }
}
</pre>
<pre class="link-defaults">
text:base;          type:argument;    spec:url
text:form;          type:element;     spec:html
text:Location;      type:http-header; spec:rfc7231
text:origin;        type:dfn;         spec:url;
text:request;       type:dfn;         spec:fetch; for:/
text:response;      type:dfn;         spec:fetch; for:/
text:URL;           type:interface;   spec:url
text:url;           type:argument;    spec:url
</pre>

<div class="non-normative">

<h2 id="intro">Introduction</h2>

<em>This section is non-normative.</em>

Client-side password management software helps improve both the security and usability of websites which require authentication. It improves security by reducing cross-site password reuse, and enhances usability by providing autofill functionality.

Sites currently lack a way to programmatically advertise where a user <span class="allow-2119">can</span> change their password. By proposing a well-known URL for changing passwords, this specification enables password managers to help users change their passwords on sites which support it.

</div>

<h2 id="infra">Infrastructure</h2>

This specification depends on the Infra Standard. [[!INFRA]]

This specification uses terminology from the
Fetch,
HTML,
HTTP, and
URL standards. [[!FETCH]] [[!HTML]] [[!HTTP-SEMANTICS]] [[!URL]]

<h2 id="semantics">Change Password URLs</h2>

A <dfn export>change password url</dfn> of an [=origin=] is a URL that points to a resource that clients can use to discover where a user should go to update their password on [=origin=].

Given an |origin|, clients <dfn export>generate a change password url</dfn> by running these steps:

1.  If |origin| is not a [=potentially trustworthy origin=], return failure.

2.  Assert: |origin| is a [=tuple origin=].

3.  Let |url| be a new {{URL}} with values set as follows:

    :   [=url/scheme=]
    ::  |origin|'s [=origin/scheme=]
    :   [=url/host=]
    ::  |origin|'s [=origin/host=]
    :   [=url/port=]
    ::  |origin|'s [=origin/port=]
    :   [=url/path=]
    ::  « ".well-known", "change-password" ».

4.  Return |url|.

<p class=example>The change password url for origin `"https://example.com/"` is `"https://example.com/.well-known/change-password"`.

Servers should redirect HTTP [=requests=] for an [=origin's=] [=change password url=] to the actual page on which users may change their password by returning a [=response=] with a [=redirect status=] of 302, 303, or 307, and a [=Location=] header. [[!FETCH]] [[!HTTP-SEMANTICS]]
Clients must handle such redirects when requesting a [=change password url=].

Note: The above paragraph restricts servers to using temporary redirect codes.
See <a href="https://github.com/WICG/change-password-url/issues/13">Issue 13</a>.

If necessary, servers may respond with an HTML document containing an <{meta/http-equiv}> pragma directive in the [=refresh state=]. [[!HTML]] Clients should handle such redirects when requesting a [=change password url=].

Servers must not locate the actual change password page at the [=change password url=], per [[WELL-KNOWN#section-1.1|RFC8615 §1.1 Appropriate Use of Well-Known URIs]]. Clients must handle [=ok status=] responses when requesting a [=change password url=].

Note: Implementations might want to use [$ToUnicode$] when displaying
[=change password url=]s. [[IDNA]]

ISSUE: Make use of [=test the reliability of an origin's response status codes=] from [[!RESPONSE-CODE-RELIABILITY]].

<h2 id="iana">IANA considerations</h2>

<h3 id="the-change-password-well-known-uri">The `change-password` well-known URI</h3>

This document defines the “`.well-known`” URI `change-password`.
This registration will be submitted to the IESG for review, approval, and registration with IANA using the template defined in [[!WELL-KNOWN]] as follows:

: URI suffix
:: change-password

: Change controller
:: W3C

: Specification document(s)
:: This document is the relevant specification. (See [[#semantics]])

: Related information:
:: None.

<h2 id="acknowedgements" class="no-num">Acknowledgements</h2>

Thanks to
Anne van Kesteren,
Cl1608Ho,
Dan Bernstein,
David Singer,
Dean Jackson,
Florian Rivoal,
John Wilander,
Maciej Stachowiak,
Mark Nottingham,
Mike West, and
Ricky Mondello
for their feedback on this proposal. All of its features are theirs and all of its bugs are mine.