Detecting the reliability of HTTP status codes

Editor’s Draft,

This version:
https://w3c.github.io/webappsec-change-password-url/response-code-reliability.html
Feedback:
public-webappsec@w3.org with subject line “[response-code-reliability] … message topic …” (archives)
Issue Tracking:
GitHub
Editors:
(Apple Inc.)
(Apple Inc.)
(Apple Inc.)

Abstract

Defines a method for detecting the reliability of an HTTP server’s response status codes.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Changes to this document may be tracked at https://github.com/w3c/webappsec.

The (archived) public mailing list public-webappsec@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “response-code-reliability” in the subject, preferably like this: “[response-code-reliability] …summary of comment…

This document was produced by the Web Application Security Working Group.

This document was produced by a group operating under the 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 document is governed by the 15 September 2020 W3C Process Document.

Introduction

This section is non-normative.

A number of specifications define well-known URIs. [WELL-KNOWN]

Clients attempting to detect the presence of well-known URIs sometimes encounter misconfigured HTTP servers which respond with a 2xx status when the resource actually doesn’t exist.

This specification defines a method for discovering if an HTTP server is misconfigured in this way.

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

2. Detecting the reliability of HTTP status codes

We can see if a web server’s statuses are reliable by fetching a URL that should never result in an ok status. If the response status (after following redirects) is an ok status, it’s safe to conclude that the server is not configured properly.

To test the reliability of an origin’s response status codes given origin, run the following steps:

  1. Let p be a new promise.

  2. If origin is not a tuple origin, reject p and return it.

  3. Let status reliability queue be the result of starting a new parallel queue.

  4. Enqueue the following steps to status reliability queue:

    1. Let url be the result of calling URL(url, base) with url "/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200" and base origin.

    2. Let request be a new request whose url is url, method is GET, synchronous flag is set, origin is origin, mode is "same-origin", service-workers mode is "none", credentials mode is "omit", cache mode is "no-store", and redirect mode is "follow".

    3. Let response be the result of performing a fetch using request.

    4. If response is a network error, reject p.

    5. If response’s status is an ok status, reject p. Otherwise, resolve p.

  5. Return p.

3. IANA considerations

3.1. The resource-that-should-not-exist-whose-status-code-should-not-be-200 well-known URI

This document defines the “.well-known” URI resource-that-should-not-exist-whose-status-code-should-not-be-200. 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

resource-that-should-not-exist-whose-status-code-should-not-be-200

Change controller

W3C

Specification document(s)

This document is the relevant specification. (See § 2 Detecting the reliability of HTTP status codes)

Related information:

None.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/
[WELL-KNOWN]
M. Nottingham. Well-Known Uniform Resource Identifiers (URIs). May 2019. Proposed Standard. URL: https://tools.ietf.org/html/rfc8615