index.src.html

<h1>Private Network Access</h1>
<pre class="metadata">
Status: CG-DRAFT
Group: WICG
ED: https://wicg.github.io/private-network-access/
Repository: wicg/private-network-access
Shortname: private-network-access
Level: 1
Editor: Titouan Rigoudy 124486, Google, titouan@google.com
Former Editor: Mike West 56384, Google, mkwst@google.com
Abstract:
  This document specifies modifications to Fetch and HTML which are intended to
  mitigate the risks associated with unintentional exposure of devices and
  servers on a client's internal network to the web at large.

  This specification was previously known as CORS-RFC1918.
Indent: 2
Boilerplate: omit conformance
Markup Shorthands: css off, markdown on
</pre>
<pre class="anchors">
spec: RFC1918; urlPrefix: https://tools.ietf.org/html/rfc1918
  type: dfn
    text: private address space; url: section-3
spec: HTML; urlPrefix: https://html.spec.whatwg.org/
  type: interface
    text: Document; url: document;
  type: abstract-op
    text: create a new browsing context; url: multipage/browsers.html#creating-a-new-browsing-context
    text: initialize the Document object; url: multipage/browsing-the-web.html#initialise-the-document-object
    text: run a worker; url: multipage/workers.html#run-a-worker
spec: FETCH; urlPrefix: https://fetch.spec.whatwg.org/
  type: abstract-op
    text: fetch; url: #concept-fetch
spec: FETCH; urlPrefix: https://fetch.spec.whatwg.org/
  type: abstract-op
    text: HTTP-network fetch; url: #concept-http-network-fetch
spec: FETCH; urlPrefix: https://fetch.spec.whatwg.org/
  type: abstract-op
    text: HTTP-network-or-cache fetch; url: #concept-http-network-or-cache-fetch
</pre>
<pre class="link-defaults">
spec:fetch; type:dfn; for:/; text:cache entry
spec:fetch; type:dfn; for:/; text:cache entry match
spec:fetch; type:dfn; for:/; text:cors check
spec:fetch; type:dfn; for:/; text:cors-preflight fetch
spec:fetch; type:dfn; for:/; text:cors-preflight cache
spec:fetch; type:dfn; for:/; text:create a new cache entry
spec:fetch; type:dfn; for:/; text:fetch params
spec:fetch; type:dfn; for:/; text:network partition key
spec:fetch; type:dfn; for:/; text:obtain a connection
spec:fetch; type:dfn; for:/; text:request
spec:fetch; type:dfn; for:/; text:response
spec:fetch; type:dfn; for:fetch params; text:request
spec:fetch; type:dfn; for:cache; text:cache match
spec:websockets; type:dfn; for:/; text:establish a websocket connection
</pre>
<pre class="biblio">
{
  "CSRF-EXPLOIT-KIT": {
    "href": "http://malware.dontneedcoffee.com/2015/05/an-exploit-kit-dedicated-to-csrf.html",
    "title": "An Exploit Kit dedicated to CSRF Pharming",
    "authors": [ "Kafeine" ]
  },
  "DRIVE-BY-PHARMING": {
    "href": "https://link.springer.com/chapter/10.1007/978-3-540-77048-0_38",
    "title": "Drive-By Pharming",
    "authors": [ "Sid Stamm", "Zulfikar Ramzan", "Markus Jakobsson" ]
  },
  "PLEX": {
    "href": "https://blog.filippo.io/how-plex-is-doing-https-for-all-its-users/",
    "title": "How Plex is doing HTTPS for all its users",
    "authors": [ "Filippo Valsorda" ]
  },
  "SECURE-LOCAL-COMMUNICATION": {
    "href": "http://www.w3.org/2015/10/28-local-minutes.html",
    "title": "Minutes from 'Secure communication with local network devices': TPAC, 2015"
  },
  "SOHO-PHARMING": {
    "href": "https://331.cybersec.fun/TeamCymruSOHOPharming.pdf",
    "title": "SOHO Pharming",
    "authors": [ "Team Cymru" ]
  },

  "AVASTIUM": {
    "href": "https://bugs.chromium.org/p/project-zero/issues/detail?id=679",
    "title": "Avast: A web-accessible RPC endpoint can launch 'SafeZone' (also called Avastium), a Chromium fork with critical security checks removed."
  },
  "TREND-MICRO": {
    "href": "https://bugs.chromium.org/p/project-zero/issues/detail?id=693",
    "title": "TrendMicro node.js HTTP server listening on localhost can execute commands"
  },

  "IPV4-REGISTRY": {
    "href": "https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml",
    "title": "IANA IPv4 Special-Purpose Address Registry"
  },
  "IPV6-REGISTRY": {
    "href": "https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml",
    "title": "IANA IPv6 Special-Purpose Address Registry"
  },

  "MIXED-CONTENT-2": {
    "href": "https://w3c.github.io/webappsec-mixed-content/level2.html",
    "title": "Mixed Content Level 2",
    "authors": ["Emily Stark", "Mike West", "Carlos Ibarra Lopez"],
    "status": "W3C First Public Working Draft",
    "date": "14 October 2020"
  },
  "LINK-LOCAL-URI": {
    "href": "https://www.ietf.org/archive/id/draft-ietf-6man-rfc6874bis-07.html",
    "title": "Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers",
    "authors": ["B. Carpenter", "S. Cheshire", "R. Hinden"],
    "status": "Internet-Draft",
    "date": "12 April 2023"
  }
}
</pre>
<style>
  ul.toc ul ul ul {
    margin: 0 0 0 2em;
  }
  ul.toc ul ul ul span.secno {
    margin-left: -9em;
  }
  table {
    border-collapse: collapse;
    width: 100%;
    caption-side: bottom;
  }
  table caption {
    padding: 5px;
  }
  th, td {
    border-width: 1px;
    border-style: solid;
    padding: 5px 10px;
  }
  th {
    background-color: lightblue;
    border-color: black;
  }
  td {
    border-color: grey;
  }
</style>
<!--
████ ██    ██ ████████ ████████   ███████
 ██  ███   ██    ██    ██     ██ ██     ██
 ██  ████  ██    ██    ██     ██ ██     ██
 ██  ██ ██ ██    ██    ████████  ██     ██
 ██  ██  ████    ██    ██   ██   ██     ██
 ██  ██   ███    ██    ██    ██  ██     ██
████ ██    ██    ██    ██     ██  ███████
-->
<section>
  <h2 id="intro">Introduction</h2>

  <em>This section is not normative.</em>

  Although [[RFC1918]] has specified a distinction between "private" and
  "public" internet addresses for over two decades, user agents haven't made
  much progress at segregating the one from the other. Websites on the public
  internet can make requests to internal devices and servers, which enable a
  number of malicious behaviors, including attacks on users' routers like those
  documented in [[DRIVE-BY-PHARMING]], [[SOHO-PHARMING]] and
  [[CSRF-EXPLOIT-KIT]].

  Here, we propose a mitigation against these kinds of attacks that would
  require internal devices to explicitly opt-in to requests from the public
  internet.

  <h3 id="goals">Goals</h3>

  The overarching goal is to prevent the user agent from inadvertently enabling
  attacks on devices running on a user's local intranet, or services running on
  the user's machine directly. For example, we wish to mitigate attacks on:

  *   Users' routers, as outlined in [[SOHO-PHARMING]]. Note that status quo
      CORS protections don't protect against the kinds of attacks discussed here
      as they rely only on [=CORS-safelisted methods=] and
      [=CORS-safelisted request-headers=]. No preflight is triggered, and the
      attacker doesn't actually care about reading the response, as the request
      itself is the CSRF attack.

  *   Software running a web interface on a user's loopback address. For better
      or worse, this is becoming a common deployment mechanism for all manner of
      applications, and often assumes protections that simply don't exist (see
      [[AVASTIUM]] and [[TREND-MICRO]] for recent examples).

  <h3 id="examples">Examples</h3>

  <h4 id="example-deny-by-default">Secure by Default</h4>

  <div class="example">
    MegaCorp Inc's routers have a fairly serious CSRF vulnerability which allows
    their DNS settings to be altered by navigating to
    `http://admin:admin@router.local/set_dns` and passing in various GET
    parameters. Oh noes!

    Happily, MegaCorp Inc's routers don't have any interest in requests from the
    public internet, and didn't take any special effort to enable them. This
    greatly mitigates the scope of the vulnerability, as malicious requests will
    generate a <a>CORS-preflight request</a>, which the router ignores. Let's
    take a closer look:

    Given `https://csrf.attack/` that contains the following HTML:

    <pre>
      &lt;iframe href="https://admin:admin@router.local/set_dns?server1=123.123.123.123"&gt;
      &lt;/iframe&gt;
    </pre>

    `router.local` will be resolved to the router's address via the magic of
    multicast DNS [[RFC6762]], and the user agent will note it as
    [=IP address space/private=]. Since `csrf.attack` resolved to a
    [=public address=], the request will trigger a [=CORS-preflight request=]:


    <pre>
      OPTIONS /set_dns?... HTTP/1.1
      Host: router.local
      <a http-header>Access-Control-Request-Method</a>: GET
      <a http-header>Access-Control-Request-Private-Network</a>: true
      ...
      Origin: https://csrf.attack
    </pre>

    The router will receive this `OPTIONS` request, and has a number of possible
    safe responses:

    *   If it doesn't understand `OPTIONS` at all, it can return a `50X` error.
        This will cause the preflight to fail, and the actual `GET` will never
        be issued.

    *   If it does understand `OPTIONS`, it can neglect to include an
        <a http-header>`Access-Control-Allow-Private-Network`</a> header in its
        response. This will cause the preflight to fail, and the actual `GET`
        will never be issued.

    *   It can crash. Crashing is fairly safe, if inelegant.
  </div>

  <h4 id="example-opt-in">Opting-In</h4>

  <div class="example">
    Some of MegaCorp Inc's devices actually need to talk to the public internet
    for various reasons. They can explicitly opt-in to receiving requests from
    the internet by sending proper CORS headers in response to a
    <a>CORS-preflight request</a>.

    When a website on the public internet makes a request to the device, the
    user agent determines that the requestor is [=IP address space/public=], and
    the router is [=IP address space/private=]. This means that requests will
    trigger a [=CORS-preflight request=], just as above.

    The device can explicitly grant access by sending the right headers in its
    response to the preflight request. For the above request, that might look
    like:

    <pre>
      HTTP/1.1 200 OK
      ...
      <a http-header>Access-Control-Allow-Origin</a>: https://public.example.com
      <a http-header>Access-Control-Allow-Methods</a>: GET
      <a http-header>Access-Control-Allow-Credentials</a>: true
      <a http-header>Access-Control-Allow-Private-Network</a>: true
      Content-Length: 0
      ...
    </pre>
  </div>

  <h4 id="shortlinks">Navigation</h4>

  <div class="example">
    MegaCorp Inc. runs an internal link shortening service at `https://go/`, and
    its employees often email such links to each other. The email server is
    hosted at a <a>public address</a> in order to ensure that employees can work
    even when they're not at the office. How considerate!

    Clicking `https://go/*` links from `https://mail.mega.corp/` will trigger a
    <a>CORS-preflight request</a>, as it is a request from a <a>public
    address</a> to a <a>private address</a>:

    <pre>
      OPTIONS /short-links-are-short-after-shortening HTTP/1.1
      Host: go
      <a http-header>Access-Control-Request-Method</a>: GET
      <a http-header>Access-Control-Request-Private-Network</a>: true
      ...
      Origin: https://mail.mega.corp
    </pre>

    In order to ensure that employees can continue to navigate such links as
    expected, MegaCorp chooses to allow private network requests:

    <pre>
      HTTP/1.1 200 OK
      ...
      <a http-header>Access-Control-Allow-Origin</a>: https://mail.mega.corp
      <a http-header>Access-Control-Allow-Methods</a>: GET
      <a http-header>Access-Control-Allow-Credentials</a>: true
      <a http-header>Access-Control-Allow-Private-Network</a>: true
      Content-Length: 0
      ...
    </pre>

    MegaCorp's leak-prevention department is worried, though, that this access
    will allow external folks to read the location of any redirect that the
    shortener would return. They're more or less resigned to the fact that
    `https://go/shortlink` will leak, but would be sad indeed if the target
    (`https://sekrits/super-sekrit-project-with-super-sekrit-partner`) leaked
    as well.

    MegaCorp's shortlink engineers are careful to avoid this potential failure
    by returning CORS headers <em>only</em> for the preflight. The "real"
    navigation doesn't require CORS headers, and they don't actually want to
    support cross-origin requests as being CORS-same-origin:

    <pre>
      // Request:
      GET /short-links-are-short-after-shortening HTTP/1.1
      Host: go
      ...

      // Response:
      HTTP/1.1 301 Moved Permanently
      ...
      Location: https://sekrits/super-sekrit-project-with-super-sekrit-partner
    </pre>

    The navigation will proceed normally, but `mail.mega.corp` won't be
    considered CORS-same-origin with the response.
  </div>

  <h4 id="example-mixed-content">Mixed Content</h4>

  <div class="example">
    Some of MegaCorp Inc's devices lack unique origins, preventing them from
    connecting through secure channels (e.g., HTTPS). However, these devices may
    still want to communicate with the public websites. They can opt-in to an
    insecure connection with secure public websites if explicitly allowed by
    users.

    When a website with a [=potentially trustworthy origin=] on the public
    internet requests data from the device, the user agent recognizes the
    requestor as [=IP address space/public=], and the device as
    [=IP address space/private=] (not a [=potentially trustworthy origin=]).
    This triggers both a [=CORS-preflight request=] and a permission prompt to
    the user (after receiving the correct preflight response).

    Website need to explicitly claim the {{IPAddressSpace}} as a `fetch()` API
    option:

    <pre highlight="js">
      fetch("http://router.local/ping", {
        targetAddressSpace: "private",
      });
    </pre>

    The device can grant access by explicitly indicating permission and provide
    a unique device ID and a user-friendly device name in the preflight response
    headers. An example response to the above request:

    <pre>
      HTTP/1.1 200 OK
      ...
      <a http-header>Access-Control-Allow-Origin</a>: https://mail.mega.corp
      <a http-header>Access-Control-Allow-Methods</a>: GET
      <a http-header>Access-Control-Allow-Credentials</a>: true
      <a http-header>Access-Control-Allow-Private-Network</a>: true
      <a http-header>Private-Network-Access-ID</a>: 01:23:45:67:89:0A
      <a http-header>Private-Network-Access-Name</a>: userA's MegaCorp device
      Content-Length: 0
      ...
    </pre>

    A permission prompt will appear, displaying the ID and name from the device
    header. If the user grants permission, the request will proceed.
  </div>
</section>

<section>
  <h2 id="framework">Framework</h2>

  <h3 id="ip-address-space-heading">IP Address Space</h3>

  Define {{IPAddressSpace}} as follows:
  <pre class="idl">
    enum IPAddressSpace { "public", "private", "local" };
  </pre>

  Every IP address belongs to an
  <dfn export local-lt="address space">IP address space</dfn>, which can be one
  of three different values:

  1.  <dfn for="IP address space" export>local</dfn>: contains the local
      host only. In other words, addresses whose target differs for every
      device.
  1.  <dfn for="IP address space" export>private</dfn>: contains
      addresses that have meaning only within the current network. In other
      words, addresses whose target differs based on network position.
  1.  <dfn for="IP address space" export>public</dfn>: contains all
      other addresses. In other words, addresses whose target is the same for
      all devices globally on the IP network.

  For convenience, we additionally define the following terms:

  1.  A <dfn>local address</dfn> is an IP address whose [=/IP address space=] is
      [=IP address space/local=].
  1.  A <dfn>private address</dfn> is an IP address whose [=/IP address space=]
      is [=IP address space/private=].
  1.  A <dfn>public address</dfn> is an IP address whose [=/IP address space=]
      is [=IP address space/public=].

  An [=/IP address space=] |lhs| is
  <dfn for="IP address space" export>less public</dfn> than an
  [=/IP address space=] |rhs| if any of the following conditions holds true:

  1.  |lhs| is [=IP address space/local=] and |rhs| is either
      [=IP address space/private=] or [=IP address space/public=].
  1.  |lhs| is [=IP address space/private=] and |rhs| is
      [=IP address space/public=].

  To <dfn export>determine the IP address space</dfn> of an IP address
  |address|, run the following steps:

  1.  If |address| belongs to the `::ffff:0:0/96` "IPv4-mapped Address"
      address block, then replace |address| with its embedded IPv4 address.
  1.  For each |row| in the
      <a href="#non-public-ip-address-blocks">Non-public IP address blocks"</a>
      table:
      1.   If |address| belongs to |row|'s address block, return |row|'s
           address space.
  1.  Return [=IP address space/public=].

  <table id="non-public-ip-address-blocks">
    <caption>Non-public IP address blocks</caption>
    <thead>
      <tr>
        <th>Address block</th>
        <th>Name</th>
        <th>Reference</th>
        <th>Address space</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>`127.0.0.0/8`</td>
        <td>IPv4 Loopback</td>
        <td>[[RFC1122]]</td>
        <td>[=IP address space/local=]</td>
      </tr>
      <tr>
        <td>`10.0.0.0/8`</td>
        <td>Private Use</td>
        <td>[[RFC1918]]</td>
        <td>[=IP address space/private=]</td>
      </tr>
      <tr>
        <td>`100.64.0.0/10`</td>
        <td>Carrier-Grade NAT</td>
        <td>[[RFC6598]]</td>
        <td>[=IP address space/private=]</td>
      </tr>
      <tr>
        <td>`172.16.0.0/12`</td>
        <td>Private Use</td>
        <td>[[RFC1918]]</td>
        <td>[=IP address space/private=]</td>
      </tr>
      <tr>
        <td>`192.168.0.0/16`</td>
        <td>Private Use</td>
        <td>[[RFC1918]]</td>
        <td>[=IP address space/private=]</td>
      </tr>
      <tr>
        <td>`198.18.0.0/15`</td>
        <td>Benchmarking</td>
        <td>[[RFC2544]]</td>
        <td>[=IP address space/local=]</td>
      </tr>
      <tr>
        <td>`169.254.0.0/16`</td>
        <td>Link Local</td>
        <td>[[RFC3927]]</td>
        <td>[=IP address space/private=]</td>
      </tr>
      <tr>
        <td>`::1/128`</td>
        <td>IPv6 Loopback</td>
        <td>[[RFC4291]]</td>
        <td>[=IP address space/local=]</td>
      </tr>
      <tr>
        <td>`fc00::/7`</td>
        <td>Unique Local</td>
        <td>[[RFC4193]]</td>
        <td>[=IP address space/private=]</td>
      </tr>
      <tr>
        <td>`fe80::/10`</td>
        <td>Link-Local Unicast</td>
        <td>[[RFC4291]]</td>
        <td>[=IP address space/private=]</td>
      </tr>
      <tr>
        <td>`::ffff:0:0/96`</td>
        <td>IPv4-mapped</td>
        <td>[[RFC4291]]</td>
        <td>see mapped IPv4 address</td>
      </tr>
    </tbody>
  </table>

  User Agents MAY allow certain IP address blocks' [=address space=] to be
  overridden through administrator or user configuration. This could prove
  useful to protect e.g. IPv6 intranets where most IP addresses are considered
  [=IP address space/public=] per the algorithm above, by instead configuring
  user agents to treat the intranet as [=IP address space/private=].

  Note: Link-local IP addresses such as `169.254.0.0/16` are considered
  [=IP address space/private=], since such addresses can identify the same
  target for all devices on a network link. A previous version of this
  specification considered them to be [=IP address space/local=] instead.

  Note: Link-local IP addresses lose their meaning if shared across links. This
  is not fundamentally different from non-public IP addresses, which all have
  some degree of locality beyond which they become ambiguous, but it does
  present a particular risk of confused deputy issues. [[LINK-LOCAL-URI]]
  attempts to solve this problem by defining a syntax for link-local IP
  addresses in URIs.

  Note: The contents of each [=/IP address space=] were at one point determined
  in accordance with the IANA Special-Purpose Address Registries
  ([[IPV4-REGISTRY]] and [[IPV6-REGISTRY]]) and the `Globally Reachable` bit
  defined therein. This turned out to be an inaccurate signal for our uses, as
  described in
  [spec issue #50](https://github.com/WICG/private-network-access/issues/50).

  ISSUE(36): Remove the special case for IPv4-mapped IPv6 addresses once access
  to these addresses is blocked entirely.

  <h3 id="private-network-request-heading">Private Network Request</h3>

  A [=request=] (|request|) is a <dfn export>private network request</dfn>
  if |request|'s [=request/current url=]'s {{URL/host}} maps to an IP address
  whose [=/IP address space=] is [=IP address space/less public=] than
  |request|'s [=request/policy container=]'s
  [=policy container/IP address space=].

  The classification of IP addresses into three broad [=address spaces=] is an
  imperfect and theoretically-unsound approach. It is a proxy used to determine
  whether two network endpoints should be allowed to communicate freely or not,
  in other words whether endpoint A is reachable from endpoint B without
  pivoting through the user agent on endpoint C.

  This approach has some flaws:

  - false positives: an intranet server with a [=public address=] might not be
    able to directy issue requests to another server on the same intranet with
    a [=private address=].
  - false negatives: a client connected to two different
    [=IP address space/private=] networks, say a home network and a VPN, might
    allow a website served from the VPN to access devices on the home network.
    See also the issue below.

  Even so, this specification aims to offer a pragmatic solution to a security
  issue that broadly affects most users of the Web whose network configurations
  are not so complex.

  ISSUE(39): The definition of [=private network requests=] could be expanded to
  cover all cross-origin requests for which the [=request/current url=]'s
  {{URL/host}} maps to an IP address whose [=/IP address space=] is not
  [=IP address space/public=]. This would prevent a malicious server on the
  private network from attacking other servers. The effort require to ship such
  a change is not deemed worth the payoff for now. This can be shipped as an
  incremental improvement later on.

  NOTE: Some [=private network requests=] are more challenging to secure than
  others. See [[#rollout-difficulties]] for more details.

  <h3 id="headers">Additional CORS Headers</h3>

  The <dfn export http-header>`Access-Control-Request-Private-Network`</dfn>
  indicates that the [=request=] is a [=private network request=].

  The <dfn export http-header>`Access-Control-Allow-Private-Network`</dfn>
  indicates that a resource can be safely shared with external networks.

  Note: These headers were briefly specified as
  `Access-Control-Request-Local-Network` and
  `Access-Control-Allow-Local-Network`, but this decision was reversed due to
  its compatibility impact. See
  [issue #91](https://github.com/WICG/private-network-access/issues/91) for
  details.

  The <dfn export http-header>`Private-Network-Access-Name`</dfn> attempts to
  provide users a human friendly name in the private network access
  permission prompt.

  The <dfn export http-header>`Private-Network-Access-ID`</dfn> header is used
  in the {{PrivateNetworkAccessPermissionDescriptor}} to identify identical
  devices across IP addresses.

  <h3 id="csp">The `treat-as-public-address` Content Security Policy Directive</h3>

  The <dfn>treat-as-public-address</dfn> directive instructs the user agent to
  treat a document as though it was served from a [=public address=], even if
  it was actually served from a [=private address=] or a [=local address=]. That
  is, it is a mechanism by which non-public documents may drop the privilege to
  contact other non-public documents without a preflight.

  The directive's syntax is described by the following ABNF grammar:

  <pre dfn-type="grammar" link-type="grammar">
    directive-name  = "treat-as-public-address"
    directive-value = ""
  </pre>

  This directive has no reporting requirements; it will be ignored entirely when
  delivered in a `Content-Security-Policy-Report-Only` header, or within
  a <{meta}> element.

  This directive's [=directive/initialization=] algorithm is as follows. Given
  an [=environment settings object=] (|context|), a `Response` (|response|), and
  a `policy` (|policy|):

  1.  Set |context|'s [=environment settings object/policy container=]'s
      [=policy container/IP address space=] to [=IP address space/public=] if
      |policy|'s [=policy/disposition=] is "`enforce`".

  <h3 id="feature-detect">Feature Detection</h3>

  A previous version of this specification proposed adding an `addressSpace`
  enum property to {{Document}} and {{WorkerGlobalScope}}, but it was removed
  due to fingerprinting concerns (see
  [issue #21](https://github.com/WICG/private-network-access/issues/21)).

  Documents should not behave differently or not based on whether the UA
  implements this specification or not - all documents should assume it does.

  <h3 id="permission-prompt">Permission Prompt</h3>

  Following the discussions in
  [[Issue#23](https://github.com/WICG/private-network-access/issues/23)], the
  private network access permission prompt is introduced to relax mixed content
  checks.

  The goal of the permission is to allow communication from public websites to
  local network servers over HTTP, which would otherwise be prevented by the
  <a href="#secure-context-restriction">secure context restriction</a> and mixed
  content checks. Migrating private network servers to HTTPS has indeed proven
  to be often difficult, even sometimes impossible.

  A new parameter is added to the `fetch()` options bag:
  <pre highlight="js">
    fetch("http://router.local/ping", {
      targetAddressSpace: "private",
    });
  </pre>
  This instructs the browser to allow the fetch even though the scheme is
  non-secure and obtain a connection to the target server. The new `fetch()` API
  is backward-compatible.

  Note that this feature cannot be abused to bypass mixed content in general.
  If the remote IP address does not belong to the IP address space specified as
  the `targetAddressSpace` option value, then the request is failed. If it does
  belong, then a CORS preflight request is sent. The target server then responds
  with a CORS preflight response, augmented with the following two headers:
  <pre>
    Private-Network-Access-Name: &lt;some human-readable device self-identification&gt;
    Private-Network-Access-ID: &lt;some unique and stable machine-readable ID, such as a MAC address&gt;
  </pre>

  For example:
  <pre>
    Private-Network-Access-Name: "My Smart Toothbrush"
    Private-Network-Access-ID: "01:23:45:67:89:0A"
  </pre>

  <a http-header>`Private-Network-Access-ID`</a> should be a 48-bit value presented as 6
  hexadecimal bytes separated by colons.
  <a http-header>`Private-Network-Access-Name`</a> should be a valid name which is a string that matches
  the [ECMAScript] regexp /^[a-z0-9_-.]+$/. 248 is the maximum number of UTF-8
  code units in the name.

  A prompt is then shown to the user asking for permission to access the target
  device. The `-Name` header is used to present a friendly string to the user
  instead of, or in addition to, an origin (often a raw IP literal). The `-ID`
  header is used to key the permission and recognize the device across IP
  addresses. Indeed, widespread use of DHCP means that devices are likely to
  change IP addresses regularly, and we would like to avoid both cross-device
  confusion and permission fatigue.

  If the user decides to grant the permission, then the fetch continues. If not,
  it fails. The permission is then persisted. The next document belonging to the
  same initiator origin that declares its intent to access the same server
  (perhaps at a different origin, if using a raw IP address) does not trigger a
  permission prompt. The initial CORS preflight response carries the same ID,
  and the browser recognizes that the document already has permission to access
  the server.

  If there's no existing `-Name` or `-ID`, the prompt is shown only with the IP
  address. If the user decides to grant the permission, then the fetch continues.
  The permission stores as an ephemeral permission and only persists for the
  current window process.

</section>

<!-- Big Text: Integrations -->
<section>
  <h2 id="integrations">Integrations</h2>

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

  This document proposes a number of modifications to other specifications in
  order to implement the mitigations sketched out in the examples above. These
  integrations are outlined here for clarity, but the external documents are the
  normative references.

  <h3 id="secure-context-restriction">Secure context restriction</h4>

  UAs must not allow <a lt="secure context">non-secure</a>
  [=IP address space/public=] contexts to request resources from
  [=private addresses=], even if the private server would opt-in to such a
  request via a preflight. Making requests to [=IP address space/private=]
  resources presents risks which are mitigated by ensuring the integrity of the
  [=request/client=] which initiates the request. In particular, network
  attackers should not be able to trivially exploit an endpoint's consent to a
  non-secure origin.

  Mixed content checks [[MIXED-CONTENT-2]] prevent secure contexts from making
  requests over HTTP, so this restriction would seem to require that private
  network servers migrate to HTTPS. This is often difficult to impossible. A
  new permission prompt is introduced to allow secure contexts to make
  requests over HTTP to the private network anyway, given user consent.

  <h3 id="integration-permissions">Integration with Permissions </h3>

  This document defines a [=powerful feature=] identified by the [=powerful
  feature/name=] <dfn export permission>`"private-network-access"`</dfn>. It
  overrides the following type:

  <dl>
    <dt>[=powerful feature/permission descriptor type=]</dt>
    <dd>
      The [=powerful feature/permission descriptor type=] of the
      <a permission>`"private-network-access"`</a> feature is defined by the
      following WebIDL interface that [=dictionary/inherits=] from the
      default [=powerful feature/permission descriptor type=]:
      <pre class="idl">
        dictionary PrivateNetworkAccessPermissionDescriptor
            : PermissionDescriptor {
          DOMString id;
        };
      </pre>
    </dd>
  </dl>

  <h3 id="integration-mixed-content">Integration with Mixed Content</h3>
  The [=Should fetching request be blocked as mixed content?=] is amended to add
  the following condition to one of the **allowed** conditions:

  1.  |request|'s [=request/origin=] is not a [=potentially trustworthy origin=],
      and |request|'s [=request/target IP address space=] is [=IP address
      space/private=] or [=IP address space/local=].

  <h3 id="integration-fetch">Integration with Fetch</h3>

  This document proposes a few changes to Fetch, with the following implication:
  [=private network requests=] are only allowed if their [=request/client=] is
  a [=secure context=] **and** a [=CORS-preflight request=] to the target origin
  is successful. If the request would have been blocked as mixed content, it can
  be allowed as long as the website states its intention to access the private
  network, and users give permission.

  Note: This includes navigations. These can indeed be used to trigger CSRF
  attacks, albeit with less subtlety than with subresource requests.

  Note: [[FETCH]] does not yet integrate the details of DNS resolution into the
  [=/Fetch=] algorithm, though it does define an [=obtain a connection=]
  algorithm which is enough for this specification. Private Network Access
  checks are applied to the newly-obtained connection. Given complexities such
  as Happy Eyeballs ([[RFC6555 obsolete]], [[RFC8305]]), these checks might pass
  or fail non-deterministically for hosts with multiple IP addresses that
  straddle [=/IP address space=] boundaries.

  <h4 id="cors-preflight">CORS preflight</h4>

  The [=HTTP fetch=] algorithm should be adjusted to ensure that a preflight is
  triggered for all [=private network requests=] initiated from
  [=secure contexts=].

  The main issue here is again that the response's
  [=response/IP address space=] is not known until a connection is obtained in
  [$HTTP-network fetch$], which is layered under [=CORS-preflight fetch=].

  <h4 id="fetching">Fetching</h4>

  What follows is a sketch of a potential solution:

  1.  [=Connection=] objects are given a new
      <dfn export for="connection">IP address space</dfn> property, initially
      null. This applies to WebSocket connections too.

  1.  A new step is added to the [=obtain a connection=] algorithm immediately
      before appending |connection| to the user agent's [=connection pool=]:

      1.  Set |connection|'s [=connection/IP address space=] to
          the result of running the [=determine the IP address space=] algorithm
          on the IP address of |connection|'s remote endpoint.

          ISSUE(33): The remote endpoint concept is not specified in [[FETCH]]
          yet, hence this is still handwaving to some extent.

  1.  [=Request=] objects are given a new <dfn for="request" export>target IP
      address space</dfn> property, initially null.

  1.  [=Response=] objects are given a new
      <dfn export for="response">IP address space</dfn> property, whose value is
      an [=/IP address space=], initially null.

  1.  Define a new <dfn export>Private Network Access check</dfn> algorithm.
      Given a [=request=] |request| and a [=connection=] |connection|:

      1.  If |request|'s [=request/origin=] is a [=potentially trustworthy
          origin=] and |request|’s [=request/current URL=]’s [=request/origin=]
          is [=same origin=] with |request|’s [=request/origin=], then return
          null.

      1.  If |request|'s [=request/policy container=] is null, then return null.

          NOTE: If |request|'s [=request/policy container=] is null, then PNA
          checks do not apply to |request|. Users of the [=fetch=] algorithm
          should take care to either set |request|'s [=request/client=] to an
          [=environment settings object=] with a non-null [=environment settings
          object/policy container=] and let [=fetch=] initialize |request|'s
          [=request/policy container=] accordingly, or to directly set
          |request|'s [=request/policy container=] to a non-null value.

      1.  If |request|'s [=request/target IP address space=] is not null, then:

          1.  [=Assert=]: |request|'s [=request/target IP address space=] is not
              [=IP address space/public=].

          1.  If |connection|'s [=connection/IP address space=] is not equal to
              then |request|'s [=request/target IP address space=], then return
              a [=network error=].

          1.  Return null.

      1.  If |connection|'s [=connection/IP address space=] is
          [=IP address space/less public=] than |request|'s [=request/policy
          container=]'s [=policy container/IP address space=], then:

              1.  Let |error| be a [=network error=].

              1.  If |request|'s [=request/client=] is not a [=secure context=]
                  (including if it is null), then return |error|.

              1.  Set |error|'s [=response/IP address space=] property to
                  |connection|'s [=connection/IP address space=].

              1.  Return |error|.

      1.  Return null.

  1.  The [$fetch$] algorithm is amended to add the following step immediately
      after |request|'s [=request/policy container=] is set:

          1.  If |request|'s [=request/target IP address space=] is [=IP address
              space/public=], then return a [=network error=].

  1.  The [$HTTP-network fetch$] algorithm is amended to add 3 new steps right
      after checking that the newly-obtained <var ignore>connection</var> is not
      failure:

          1.  Set |response|'s [=response/IP address space=] to
              |connection|'s [=connection/IP address space=].

          1.  Let |privateNetworkAccessCheckResult| be the result of running
              [=Private Network Access check=] for |fetchParams|' [=request=]  and
              |connection|.

          1.  If |privateNetworkAccessCheckResult| is a [=network error=], return
              |privateNetworkAccessCheckResult|.

  1.  Define a new algorithm to <dfn>determine the preflight mode</dfn>, given a
      [=request=] |request| and a boolean |makeCORSPreflight|:

      1.  If |makeCORSPreflight| is true and one of these conditions is true:

          *   There is no method cache entry match for |request|'s
              [=request/method=] using |request|, and either |request|'s
              [=request/method=] is not a [=CORS-safelisted method=] or
              |request|'s [=request/use-CORS-preflight flag=] is set.

          *   There is at least one [=list/item=] in the CORS-unsafe
              request-header names with |request|'s [=request/header list=] for
              which there is no header-name cache entry match using |request|.

          Then:

              1.  If |request|'s [=request/target IP address space=] is not
                  null, then return "cors+pna".

              1.  Otherwise, return "cors".

      1.  If |request|'s [=request/target IP address space=] is not null, then
          return "pna".

      1.  Otherwise, return "none".

  1.  Define a new algorithm called <dfn>HTTP-no-service-worker fetch</dfn>
      based on the existing steps in [=HTTP fetch=] that are run if |response|
      is still null after handling the fetch via service workers, and amend
      those slightly as follows:

      1.  Let |preflightMode| be the result of invoking [=determine the
          preflight mode=] given |request| and |makeCORSPreflight|.

      1.  Replace the entire condition "If <var ignore>makeCORSPreflight</var>
          is true and ..., Then:" with:

          1.  If |preflightMode| is not "none", then:

      1.  Replace "running [=CORS-preflight fetch=] given |request|" with
          "running [=CORS-preflight fetch=] given |request| and
          |preflightMode|"

      1.  Immediately after running [=CORS-preflight fetch=]:

          1.  If |preflightResponse| is a [=network error=]:

              1.  If |preflightResponse|'s [=response/IP address space=] is
                  null, return |preflightResponse|.

              1.  Set |request|'s [=request/target IP address space=] to
                  |preflightResponse|'s [=response/IP address space=].

              1.  Return the result of running [=HTTP-no-service-worker fetch=]
                  given |fetchParams|.

      1.  Immediately after running [$HTTP-network-or-cache fetch$]:

          1.  If |response| is a [=network error=] and |response|'s
              [=response/IP address space=] is non-null, then:

              1.  Set |request|'s [=request/target IP address space=] to
                  |preflightResponse|'s [=response/IP address space=].

              1.  Return the result of running [=HTTP-no-service-worker fetch=]
                  given |fetchParams|.

      Note: Because |request|'s [=request/target IP address space=] is set to a
      non-null value when recursing, this recursion can go at most 1 level deep.

  1.  The [=CORS-preflight fetch=] algorithm is adjusted to take a new parameter
      |preflightMode| (default "cors"), and handle the new headers as follows:

      1.  Only append \``Accept`\` and
          \`<a http-header>`Access-Control-Request-Headers`</a>\` to
          <var ignore>preflight</var>'s [=request/header list=] if
          |preflightMode| is true.

      1.  Immediately before running [$HTTP-network-or-cache fetch$]:

          1.  If |request|'s [=request/target IP address space=] is not null,
              then:

              1.  [=header list/Set=]
                  "<a http-header>`Access-Control-Request-Private-Network`</a>"
                  to "`true`" in <var ignore>preflight</var>'s
                  [=request/header list=].

      1.  Immediately after the [=CORS check=]:

          1.  If |preflightMode| is "pna" or "cors+pna",

              1.  [=Assert=]: |request|'s [=request/target IP address space=] is
                  not null.

              1.  Let |allow| be the result of [=extracting header list values=]
                  given
                  "<a http-header>`Access-Control-Allow-Private-Network`</a>"
                  and |response|'s [=response/header list=].

              1.  If |allow| is not "`true`", return a [=network error=].

              1.  Let |requestWithoutTargetIpAddressSpace| be a copy of |request|
                  but set its [=request/target IP address space=] to be null.

              1.  If
                  <a lt="should fetching request be blocked as mixed content?">
                    should fetching |requestWithoutTargetIpAddressSpace| be
                    blocked as mixed content
                  </a> returns **allowed**, return null.

              1.  If <a http-header>`Private-Network-Access-ID`</a> or
                  <a http-header>`Private-Network-Access-Name`</a> is null or
                  empty, let |targetId| be |request|'s [=request/target IP
                  address space=]. Store the permission as an ephemeral
                  permission, then return null.

              1.  Let |targetId| be the result of [=extracting header list
                  values=] given
                  "<a http-header>`Private-Network-Access-ID`</a>" and
                  |response|'s [=response/header list=].

              1.  if |targetId| is not a string of 6 hexadecimal bytes
                  separated by colons, return a [=network error=].

              1.  Let |targetName| be the result of [=extracting header list
                  values=] given
                  "<a http-header>`Private-Network-Access-Name`</a>" and
                  |response|'s [=response/header list=].

              1.  if |targetName| does not match the [ECMAScript] regexp
                  /^[a-z0-9_-.]+$/ or has more than 248 UTF-8 code units,
                  return a [=network error=].

              1.  Let |state| be the result of [=requesting permission to use=]
                  the following descriptor:
                  <pre highlight="js">
                    {
                      name: <a permission>`"private-network-access"`</a>,
                      id: <var>targetId</var>,
                    }
                  </pre>

              1.  If |state| is {{PermissionState/"denied"}}, return a [=network
                  error=].

              1. Return null.

  1.  Finally, to mitigate the impact of DNS rebinding attacks (see
      [[#dns-rebinding]]), the [=CORS-preflight cache=] is adjusted to take
      [=/IP address space=] information into account:

      1.  A new <dfn export for="cache entry">IP address space</dfn> property
          (null or an [=/IP address space=]) is added to each [=cache entry=].

      1.  This new property is initialized by the [=create a new cache entry=]
          algorithm from |request|'s [=request/target IP address space=].

      1.  This new property is checked by the [=cache entry match=] algorithm:

          1.  <var ignore>entry</var>'s [=cache entry/IP address space=] is
              equal to |request|'s [=request/target IP address space=].

  <h4 id="fetch-api">Fetch API</h4>

  The Fetch API needs to be adjusted as well.

  - Append an optional [=map/entry=] to {{RequestInfo}}, whose [=map/key=] is
    <dfn export>targetAddressSpace</dfn>, and [=map/value=] is a
    {{IPAddressSpace}}.
      <pre class="idl">
        partial dictionary RequestInit {
          IPAddressSpace targetAddressSpace;
        };
      </pre>

  - Define a new {=targetAddressSpace=} representing the
    above in [=request=].
      <pre class="idl">
        partial interface Request {
          readonly attribute IPAddressSpace targetAddressSpace;
        };
      </pre>

  - The <a constructor for=Request lt="Request(input, init)"><code>new
    Request(<var ignore=''>input</var>, |init|)</code></a> is
    appended with the following step right before setting [=this=]'s [=request=]
    to |request|:
    1.  If |init|["{{RequestInit/targetAddressSpace}}"] [=map/exists=], then
        switch on |init|["{{RequestInit/targetAddressSpace}}"]:
        <dl class=switch>
          <dt>public
            <dd>Do nothing.

          <dt>private
          <dd>Set |request|'s [=target IP address space=] to [=IP address
            space/private=].

          <dt>local
          <dd>Set |request|'s [=target IP address space=] to [=IP address
            space/local=].
        </dl>

  <h4 id="forbidden-header-names">Forbidden header names</h4>

  A new entry is added to the list of [=forbidden request-header=] names:
  <a http-header>`Access-Control-Request-Private-Network`</a>.

  The user agent should have full control over this header, just as it does over
  other CORS headers.

  <h3 id="integration-websockets">Integration with WebSockets</h3>

  ISSUE(14): Preflight requests should probably be sent ahead of WebSocket
  handshakes, given that WebSocket handshakes have roughly the same capabilities
  as `<img>` tags. This might require no additional work to specify given that
  the [=establish a WebSocket connection=] depends on the [=/Fetch=] algorithm.

  A previous version of this specification proposed simply adding the new
  headers (see [[#headers]]) to the WebSocket handshake. This would not be
  sufficient to fully guard against CSRF attacks, however.

  <h3 id="integration-html">Integration with HTML</h3>

  To support the checks in [[FETCH]], user agents must remember the source
  [=/IP address space=] of contexts in which network requests are made. To this
  effect, the [[HTML]] specification is patched as follows:

  1.  A new <dfn export for="policy container">IP address space</dfn> property
      is added to the [=/policy container=] [=struct=].

      1.  It is initially [=IP address space/public=].

  1.  An additional step is added to the [=clone a policy container=]
      algorithm:

      1.  Set <var ignore>clone</var>'s [=policy container/IP address space=] to
          <var ignore>policyContainer</var>'s
          [=policy container/IP address space=].

  1.  An additional step is added to the [=create a policy container from a
      fetch response=] algorithm:

      1.  Set <var ignore>result</var>'s [=policy container/IP address space=]
          to <var ignore>response</var>'s [=response/IP address space=].

  <div class="example">
    Assuming that `example.com` resolves to a [=public address=] (say,
    `123.123.123.123`), then the {{Document}} created when navigating to
    `https://example.com/document.html` will have its
    [=Document/policy container=]'s [=policy container/IP address space=]
    property set to [=IP address space/public=].

    If this {{Document}} then embeds an `about:srcdoc` iframe, then the child
    frame's {{Document}} will have its [=Document/policy container=]'s
    [=policy container/IP address space=] property set to
    [=IP address space/public=].

    If, on the other hand, `example.com` resolved to a [=local address=]
    (say, `127.0.0.1`), then the {{Document}} created when navigating to
    `https://example.com/document.html` will have its
    [=Document/policy container=]'s [=policy container/IP address space=]
    property set to [=IP address space/local=].
  </div>

  <h3 id="workers">Workers</h3>

  *This section is non-normative.*

  Given that {{WorkerGlobalScope}} already has a
  [=WorkerGlobalScope/policy container=] field populated using the [=create a
  policy container from a fetch response=] algorithm, the avove integrations
  with Fetch and HTML apply just as well to worker contexts as to documents.

  <div class="example">
    Assuming that `example.com` resolves to a [=public address=] (say,
    `123.123.123.123`), then a {{WorkerGlobalScope}} created by fetching a
    script from `https://example.com/worker.js` will have its
    [=WorkerGlobalScope/policy container=]'s
    [=policy container/IP address space=] property set to
    [=IP address space/public=].

    Any fetch [=request=] initiated by this worker that [=obtains a connection=]
    to an IP address in the [=IP address space/private=] or
    [=IP address space/local=] [=address spaces=] would then be a
    [=private network request=].
  </div>

  ISSUE(83): The [=/Service Worker=] <a spec="service-workers">soft update</a>
  algorithm unfortunately sets a [=request/client|request client=] of `"null"`
  when [=fetching=] an updated script. This causes all sorts of issues, and
  interferes with the [=private network access check=] algorithm laid out above.
  Indeed, there is no [=request/client|request client=] from which to copy the
  [=request/policy container=] during [=fetch=].

</section>

<section>
  <h2 id="implementation-considerations">Implementation Considerations</h2>

  <h3 id="file-url">Where do `file` URLs fit?</h3>

  It isn't entirely clear how `file` URLs fit into the public/private scheme
  outlined above. It would be nice to prevent folks from harming themselves by
  opening a malicious HTML file locally, on the one hand, but on the other, code
  running locally is somewhat outside of any coherent threat model.

  For the moment, let's err on the side of treating `file` URLs as
  [=IP address space/local=], as they seem to be just as much a part of the local
  system as anything else on a loopback address.

  ISSUE: Reevaluate this after implementation experience.

  <h3 id="proxies">Proxies</h3>

  In the current implementation of this specification in Chromium, proxies
  influence the [=address space=] of resources they proxy. Specifically,
  resources fetched via proxies are considered to have been fetched from the
  proxy's IP address itself.

  <div class="example">
    If a {{Document}} served by `foo.example` on a [=public address=] is fetched
    by the user agent via a proxy on a [=private address=], then the
    {{Document}}'s [=Document/policy container=]'s
    [=policy container/IP address space=] is set to
    [=IP address space/private=].

    The {{Document}} will in turn be allowed to make requests to other
    [=private addresses=] accessible to the browser.
  </div>

  This can allow a website to learn that it was proxied by observing that it is
  allowed to make requests to [=private addresses=], which is a privacy
  information leak. While this requires correctly guessing the URL of a resource
  on the private network, a single correct guess is sufficient.

  This is expected to be relatively rare and not warrant more mitigations. After
  all, in the status quo all websites can make requests to all IP addresses with
  no restrictions whatsoever.

  It would be interesting to explore a mechanism by which proxies could tell the
  browser "please treat this resource as public/private anyway", thereby passing
  on some information about the IP address behing the proxy. This might take the
  form of the <a href="#csp">CSP directive</a> discussed above, with some minor
  modifications.

  <h3 id="http-cache">HTTP Cache</h3>

  The current implementation of this specification in Chromium interacts with
  the HTTP cache in two noteworthy ways, depending on which kind of resource is
  loaded from cache.

  <h4 id="http-cache-main-resources">Main resources</h4>

  A [=document=] constructed from a cached [=response=] remembers the IP address
  whence the [=response=] was initially loaded. The [=/IP address space=] of the
  [=document=] is derived anew from the IP address.

  In the common case, this entails that the [=document=]'s
  [=Document/policy container=]'s [=policy container/IP address space=] is
  restored unmodified. However in the event that the user agent's configuration
  has changed, the derived [=/IP address space=] might be different.

  <div class="example">
    The user agent navigates to `http://foo.example/`, loads the main resource
    from `1.2.3.4`, caches it, then sets the resulting [=document=]'s
    [=Document/policy container=]'s [=policy container/IP address space=] to
    [=IP address space/public=].

    The user agent then restarts, and a new configuration is applied specifying
    that `1.2.3.4` should be classified as a [=private address=] instead.

    The user agent navigates to `http://foo.example/` once more and loads the
    main resource from the HTTP cache. The resulting [=document=]'s
    [=Document/policy container=]'s [=policy container/IP address space=] is
    now set to [=IP address space/private=].
  </div>

  <h4 id="http-cache-subresources">Subresources</h4>

  Subresources loaded from the HTTP cache are subject to the
  [=Private Network Access check=]. This is not yet reflected in the algoritms
  above, since that check is only applied in [$HTTP-network fetch$].

  ISSUE(75): Specify and explain Chromium's behavior here.

  See [[#http-cache-security]] for a discussion of security implications.

  <h3 id="rollout-difficulties">Rollout difficulties</h3>

  Private Network Access essentially deprecates direct access to the private
  network in favor of more secure user-agent-mediated alternatives. Web
  deprecations are hard. Chromium has encountered many stumbling blocks on the
  way to shipping parts of this specification.

  In particular, shipping restrictions on fetches from [=non-secure contexts=]
  in the [=IP address space/private=] [=/IP address space=] to the
  [=IP address space/local=] [=/IP address space=] has proven particularly
  difficult, for a lower payoff. Indeed, exploiting such fetches requires
  attackers to already have a foothold in the private network, which
  substantially raises attack difficulty. As a result, Chromium exempted these
  fetches from restrictions temporarily, choosing to focus on fetches from the
  [=IP address space/public=] [=/IP address space=].

</section>

<section>
  <h2 id="security-and-privacy-considerations">Security and Privacy Considerations</h2>

  <h3 id="user-mediation">User Mediation</h3>

  The proposal in this document only ensures that the device consents to access
  from the public internet. Users agents MAY ensure that the *user* consents to
  such access as well, as it might be in their interests to deny such access,
  even though the device itself would allow it.

  This mediation could be done via an explicit permission grant, via some sort
  of pairing ceremony a la
  <a href="https://en.wikipedia.org/wiki/Password-authenticated_key_agreement">PAKE</a>,
  or any other clever interface which the user agent might devise.

  <h3 id="mixed-content">Mixed Content</h3>

  The CORS restrictions added by the proposal in this document do not obviate
  mixed content checks [[MIXED-CONTENT-2]]. Device consent obtained through a
  CORS preflight request is necessary but not sufficient.

  Note: [[MIXED-CONTENT-2]] does not prevent secure contexts from fetching
  resources from [=/origins=] whose [=origin/host=] is `localhost` or an IP
  address in the `127.0.0.0/8` or `::1/128` blocks. See also the definition of
  [=potentially trustworthy origins=].

  Developers who wish to fetch [=IP address space/private=] or
  [=IP address space/local=] resources (from hosts other than the above
  exceptions) from [=IP address space/public=] pages MUST ensure that the
  connection is secure. This might involve a solution along the lines of
  [[PLEX]], where Web PKI certificates are issued to user-specific domain names
  that then resolve to private IP addresses which only make sense on the user's
  private network.

  ISSUE(23): Some consumer routers implement overly-aggressive protections
  against DNS rebinding attacks by simply blocking DNS responses that resolve to
  non-public IP addresses. This presents a stumbling block for solutions like
  [[PLEX]]. Workarounds are discussed in the linked issue.

  This problem space has been explored a few times already and seems worth
  revisiting at some point. One could imagine a pairing ceremony such as the one
  hinted at above, or one of the ideas floated in
  [[SECURE-LOCAL-COMMUNICATION]].

  <h3 id="dns-rebinding">DNS Rebinding</h3>

  The mitigation described here operates upon the IP address which the user
  agent actually connects to when loading a particular resource. This check
  MUST be performed for each new connection made, as DNS rebinding attacks
  may otherwise trick the user agent into revealing information it shouldn't.

  The modifications to the <a>CORS-preflight cache</a> are intended to mitigate
  this attack vector.

  <h3 id="scope-mitigation">Scope of Mitigation</h3>

  The proposal in this document merely mitigates attacks against private web
  services, it cannot fully solve them. For example, a router's
  web-based administration interface must be designed and implemented to defend
  against CSRF on its own, and should not rely on a UA that behaves as specified
  in this document. The mitigation this document specifies is necessary given
  the reality of private web service implementation quality today, but vendors
  should not consider themselves absolved of responsibility, even if all UAs
  implement this mitigation.

  <h3 id="cross-network-confusion">Cross-network confusion</h3>

  Most private networks cannot communicate with each other, yet they are all
  treated by this specification as belonging to the [=IP address space/private=]
  [=/IP address space=]. Going further, [=private addresses=] have meaning only
  on the private network where they are used. The same IP address might refer to
  entirely different devices in two different networks.

  This opens the door to cross-network attacks:

  -   A user connects to two different private networks: a home Wi-Fi network
      and a corporate VPN. Their smart fridge has been hacked. They open their
      smart fridge's web interface, which then performs CSRF attacks against
      corporate websites accessible via the VPN.
  -   A user connects to a malicious internet cafe Wi-Fi, which requires users
      to keep a captive portal page open. They close their laptop, go home, open
      up their laptop again. The captive portal page (either still open or
      reloaded from cache as the user agent restores its previous state)
      performs CSRF attacks against the user's home devices.
  -   A user connects to a malicious internet cafe Wi-Fi, whose captive portal
      website caches a malicious script from
      `http://router.example/popular-library.js` (the cafe network administrator
      operates a malicious DNS server) with a very long expiry. The user powers
      their computer off, goes home, boots up their computer again and visits
      their router's administration interface at `http://router.example`, which
      embeds `/popular-library.js`. The malicious script is loaded in the
      administration interface's first-party context.

  None of these attacks are novel - they are just examples of the limitations of
  this specification.

  ISSUE(28): Potential mitigations would require noticing network changes and
  clearing state specific to the previous network. Doing so in a fully general
  manner is likely to be impossible short of clearing all state. Maybe a
  practical compromise can be reached.

  <h3 id="http-cache-security">HTTP cache</h3>

  <h4 id="http-cache-security-subresources">Applying checks to subresources</h4>

  ISSUE(75): The following is no longer accurate. Implementation experience
  revealed that integrating with the cache was useful even in protecting
  network resources against CSRF attacks. This section needs to be rewritten.

  Cached subresources are not currently protected by this specification, even
  though the HTTP cache remembers the source IP address which could be used in
  the [=Private Network Access check=] algorithm during
  [$HTTP-network-or-cache fetch$].

  While it may be a good idea to fix this apparent discrepancy, it is not
  directly relevant to the main goal of this specification: preventing CSRF
  attacks.

  At most, a malicious public website might be able to determine whether a user
  has visited particular private websites in the past. This attack on the user's
  privacy is no worse than the status quo.

  In addition, due to HTTP cache partitioning, a subresource can only be loaded
  from cache by malicious attackers who manage to replicate the
  [=network partition key=] of the [=cache entry=]. One way an attacker could
  achieve this is by manipulating DNS (see also [[#dns-rebinding]]) in order to
  impersonate the top-level site that initially embedded the cached resource.

  <div class="example">
    The user agent navigates to `http://router.example`, which is served from
    `192.168.1.1`. The website embeds a logo from
    `http://router.example/$BRAND-logo.png`, which is cached.

    A malicious attacker then re-binds `router.example` to an
    attacker-controlled public IP address, and somehow tricks the user into
    visiting `http://router.example` again. The malicious website attempts to
    embed the logo, and monitors whether the load is successful. If so, the
    attacker has determined the brand of the user's router.
  </div>

  <h4 id="http-cache-poisoning">HTTP cache poisoning</h4>

  While this specification aims to protect private network servers from
  receiving requests from public websites, DNS rebinding can be used to carry
  out a similar attack through cache poisoning of unauthenticated resources.

  Attackers masquerading as `http://router.com` can cache a malicious script at
  `http://router.com/totally-legit.js`. Later on, when the user navigates to
  `http://router.com/`, the page might request the poisoned script and execute
  attacker code in a [=IP address space/less public=] [=/IP address space=].

  This attack is partially mitigated by cache partitioning,
  which makes it so that the attacker must navigate a top-level browsing context
  to `http://router.com/` before caching resources, which lacks subtlety. It is
  also not specific to Private Network Access, rather being a symptom of
  plaintext HTTP's lack of authentication and integrity protection.

</section>

<section>
  <h2 id="iana-considerations">IANA Considerations</h2>

  The Content Security Policy Directive registry should be updated with the
  following directives and references [[!RFC7762]]:

  :   <a>`treat-as-public-address`</a>
  ::  This document (see [[#csp]])
</section>

<section>
  <h2 id="acknowledgements">Acknowledgements</h2>

  Conversations with Ryan Sleevi, Chris Palmer, and Justin Schuh helped flesh
  out the contours of this proposal. Hopefully they won't hate it too much.
  Mathias Karlsson has the dubious honor of being the
  <a href="https://twitter.com/avlidienbrunn/status/680736829679755265">straw
  that broke the camel's back</a>, and Brian Smith's contributions to the
  resulting thread were useful, as always.
</section>