Add some information for authors about the intent of the spec

index.bs

@@ -117,7 +117,7 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
   of the representation of the resource the author expects to load. For instance,
   an author may wish to load some framework from a shared server rather than hosting it
   on their own origin. Specifying that the <em>expected</em> SHA-384 hash of
-  `https://example.com/example-framework.js`
+  `https://example.com/v1.0/example-framework.js`
   is `Li9vy3DqF8tnTXuiaAJuML3ky+er10rcgNR/VqsVpcw+ThHmYcwiB1pbOxEbzJr7` means
   that the user agent can verify that the data it loads from that URL matches
   that expected hash before executing the JavaScript it contains. This
@@ -129,12 +129,17 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
 
   <div class="example">
   <pre>
-    &lt;script src="https://example.com/example-framework.js"
+    &lt;script src="https://example.com/v1.0/example-framework.js"
             integrity="sha384-Li9vy3DqF8tnTXuiaAJuML3ky+er10rcgNR/VqsVpcw+ThHmYcwiB1pbOxEbzJr7"
             crossorigin="anonymous"&gt;&lt;/script&gt;
   </pre>
   </div>
 
+  In the event that the expected hash does not match the hash of the downloaded
+  resource, indicating a potential compromise of the server, the user agent will
+  refuse to parse or execute the resource, and will fire an error to alert
+  developers to the failure.
+
   Scripts, of course, are not the only response type which would benefit
   from integrity validation. The scheme specified here also applies to `link`
   and future versions of this specification are likely to expand this coverage.
@@ -164,7 +169,7 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
 
       <div class="example">
       <pre>
-          &lt;link rel="stylesheet" href="https://site53.example.net/style.css"
+          &lt;link rel="stylesheet" href="https://site53.example.net/v1.0/style.css"
                 integrity="sha384-+/M6kredJcxdsqkczBUjMLvqyHb1K/JThDXWsBVxMEeZHEaMKEOEct339VItX1zB"
                 crossorigin="anonymous"&gt;
       </pre>
@@ -322,7 +327,7 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
   To allow authors to switch to stronger hash functions without being held back by older
   user agents, validation using unsupported hash functions acts like no integrity value
   was provided (see the [[#does-response-match-metadatalist]] algorithm below).
-  Authors  are encouraged to use strong hash functions, and to begin migrating to
+  Authors are encouraged to use strong hash functions, and to begin migrating to
   stronger hash functions as they become available.
 
   ### Priority ### {#priority}
@@ -411,7 +416,7 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
 
   <div class="example">
   <pre>
-      &lt;script src="https://example.com/example-framework.js"
+      &lt;script src="https://example.com/v1.0/example-framework.js"
               integrity="sha384-Li9vy3DqF8tnTXuiaAJuML3ky+er10rcgNR/VqsVpcw+ThHmYcwiB1pbOxEbzJr7
                          sha384-+/M6kredJcxdsqkczBUjMLvqyHb1K/JThDXWsBVxMEeZHEaMKEOEct339VItX1zB"
               crossorigin="anonymous"&gt;&lt;/script&gt;
@@ -463,7 +468,7 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
   applied only to the `hash-expression` that immediately precedes it.
 
   In order for user agents to remain fully forwards compatible with future
-  options, the user agent MUST ignore all unrecognized  `option-expression`s.
+  options, the user agent MUST ignore all unrecognized `option-expression`s.
 
   Note: Note that while the `option-expression` has been reserved in the syntax,
   no options have been defined. It is likely that a future version of the spec
@@ -472,7 +477,7 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
 
   ## Handling integrity violations ## {#handling-integrity-violations}
 
-  The user agent will refuse to render or execute responses that fail an integrity
+  The user agent MUST refuse to render or execute responses that fail an integrity
   check, instead returning a network error as defined in Fetch [[!Fetch]].
 
   Note: On a failed integrity check, an `error` event is fired. Developers
@@ -511,8 +516,8 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
   the digest in-flight (or remove it entirely, or do absolutely anything else to
   the document), just as they could alter the response the hash is meant to
   validate.  Thus, it is recommended that authors deliver integrity metadata only
-  to a <a>Secure Context</a>. See also  <a
-  href="http://www.w3.org/2001/tag/doc/web-https ">Securing the Web</a>.
+  to a <a>Secure Context</a>. See also <a
+  href="http://www.w3.org/2001/tag/doc/web-https">Securing the Web</a>.
 
   ## Hash collision attacks ## {#hash-collision-attacks}
 
@@ -558,6 +563,52 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
 
   <!-- ####################################################################### -->
 
+  # Authoring Considerations # {#authoring-considerations}
+
+  <em>This section is not normative.</em>
+
+  ## Versioned resources ## {#versioned-resources}
+
+  <a>Integrity metadata</a> is only useful if the resource can be reasonably
+  guaranteed to remain the same. It is therefore important that if resources
+  are updated they receive a new URL. Typically this might take the form of a
+  version number as part of the path or file name, which would ensure that a
+  resource would only be expected to change as a result of a compromised
+  server.
+
+  <div class="example">
+  <pre>
+    &lt;script src="https://example.com/v1.0/example-framework.js"
+            integrity="sha384-Li9vy3DqF8tnTXuiaAJuML3ky+er10rcgNR/VqsVpcw+ThHmYcwiB1pbOxEbzJr7"
+            crossorigin="anonymous"&gt;&lt;/script&gt;
+  </pre>
+  </div>
+
+  ## Coping with errors ## {#coping-with-errors}
+
+  When an integrity violation is detected, the resource will not parse or
+  execute. This could cause problems for users, so the system should be
+  designed to cope with errors.
+
+  If an alerting or logging system exists, the integrity error should be
+  sent to that so that the violation can be resolved safely.
+
+  The integrity error could also trigger the system to attempt to load the
+  resource from a local copy instead of a CDN or other third-party server.
+  It is worth evaluating if a local resource may be a better initial choice
+  rather than using a resource hosted on a CDN.
+
+  If the resource cannot be made available to the system, then the system
+  should be built to cope as best as possible with the resource's absence.
+  For some resources, for example web fonts or non-essential styles, there
+  may be no work to do to leave the system in a usable state. Alternatively,
+  the system could be built using progressive enhancement principles, where
+  in the absence of a resource, or support from the user agent for that
+  resource, the system remains usable although potentially with degraded
+  functionality.
+
+  <!-- ####################################################################### -->
+
   # Acknowledgements # {#acknowledgements}
 
   Much of the content here is inspired heavily by Gervase Markham's <a
@@ -567,5 +618,5 @@ spec: SHA2; urlPrefix: http://csrc.nist.gov/publications/fips/fips180-4/fips-180
 
   A special thanks to Mike West for his invaluable contributions to the initial
   version of this spec. Thanks to Brad Hill, Anne van Kesteren, Jonathan
-  Kingston, Mark Nottingham,  Sergey Shekyan , Dan Veditz, Eduardo Vela,
+  Kingston, Mark Nottingham, Sergey Shekyan, Dan Veditz, Eduardo Vela,
   Tanvi Vyas, and Michal Zalewski for providing invaluable feedback.