Skip to content

Commit de06e8d

Browse files
mikewestmikewest
committed
CLEAR: Adding example markup.
1 parent 3f50f9f commit de06e8d

File tree

2 files changed

+144
-111
lines changed

2 files changed

+144
-111
lines changed

‎specs/clear-site-data/index.html

Lines changed: 75 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -330,39 +330,47 @@ <h3 class="heading settled" data-level="1.1" id="examples"><span class="secno">1
330330

331331
<h4 class="heading settled" data-level="1.1.1" id="example-signout"><span class="secno">1.1.1. </span><span class="content">Signing Out</span><a class="self-link" href="#example-signout"></a></h4>
332332

333-
334-
<p>A user signs out of Super Secret Social Network via a CSRF-protected POST to
335-
<code>https://supersecretsocialnetwork.example.com/logout</code>, and the site
336-
author wishes to ensure that locally stored data is removed as a result.</p>
333+
334+
<div class="example" id="example-fe709765"><a class="self-link" href="#example-fe709765"></a>
335+
A user signs out of Super Secret Social Network via a CSRF-protected POST to
336+
<code>https://supersecretsocialnetwork.example.com/logout</code>, and the
337+
site author wishes to ensure that locally stored data is removed as a
338+
result.
337339

338340

339-
<p>They can do so by sending the following HTTP header in the response:</p>
341+
<p>They can do so by sending the following HTTP header in the response:</p>
342+
340343

341-
342-
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: *
344+
345+
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: <a data-link-type="dfn" href="#">*</a>
343346
</pre>
347+
348+
349+
</div>
344350

345351

346352
<h4 class="heading settled" data-level="1.1.2" id="example-targeted"><span class="secno">1.1.2. </span><span class="content">Targeted Clearing</span><a class="self-link" href="#example-targeted"></a></h4>
347353

348-
349-
<p>A user signs out of Megacorp Inc.'s site via a CSRF-protected POST to
350-
<code>https://megacorp.example.com/logout</code>. Megacorp has a large number
351-
of services available as subdomains, so many that it’s not entirely clear
352-
which of them would be safe to clear as a response to a logout action. One
353-
option would be to simply clear everything, and deal with the fallout.
354-
Megacorp’s CEO, however, once lost hours and hours of progress in "Irate
355-
Ibexes" due to inadvertant site-data clearing, and so refuses to allow such
356-
a sweeping impact to the site’s users.</p>
354+
355+
<div class="example" id="example-0b8e3ea5"><a class="self-link" href="#example-0b8e3ea5"></a>
356+
A user signs out of Megacorp Inc.'s site via a CSRF-protected POST to
357+
<code>https://megacorp.example.com/logout</code>. Megacorp has a large
358+
number of services available as subdomains, so many that it’s not entirely
359+
clear which of them would be safe to clear as a response to a logout action.
360+
One option would be to simply clear everything, and deal with the fallout.
361+
Megacorp’s CEO, however, once lost hours and hours of progress in "Irate
362+
Ibexes" due to inadvertant site-data clearing, and so refuses to allow such
363+
a sweeping impact to the site’s users.
357364

358365

359-
<p>The developers know, however, that the "Minus" application is certainly safe
360-
to clear out. They can target this specific subdomain by including a request
361-
to that subdomain as part of the logout landing page (ideally as a
362-
CORS-enabled, CSRF-protected POST):</p>
366+
<p>The developers know, however, that the "Minus" application is certainly safe
367+
to clear out. They can target this specific subdomain by including a request
368+
to that subdomain as part of the logout landing page (ideally as a
369+
CORS-enabled, CSRF-protected POST):</p>
370+
363371

364-
365-
<pre>fetch("https://minus.megacorp.example.com/clear-site-data",
372+
373+
<pre>fetch("https://minus.megacorp.example.com/clear-site-data",
366374
{
367375
method: "POST",
368376
mode: "cors",
@@ -371,56 +379,72 @@ <h4 class="heading settled" data-level="1.1.2" id="example-targeted"><span class
371379
})
372380
});
373381
</pre>
382+
374383

375384

376-
<p>That endpoint would return proper CORS headers in response to that request’s
377-
preflight, and would return the following header for the actual request:</p>
385+
<p>That endpoint would return proper CORS headers in response to that request’s
386+
preflight, and would return the following header for the actual request:</p>
387+
378388

379-
380-
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: *; <a data-link-type="dfn" href="#includesubdomains">includeSubdomains</a>
389+
390+
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: <a data-link-type="dfn" href="#">*</a>; <a data-link-type="dfn" href="#includesubdomains">includeSubdomains</a>
381391
</pre>
392+
393+
394+
</div>
382395

383396

384397
<h4 class="heading settled" data-level="1.1.3" id="example-keepcookies"><span class="secno">1.1.3. </span><span class="content">Keep Critical Cookies</span><a class="self-link" href="#example-keepcookies"></a></h4>
385398

386-
387-
<p>A user opts-out of interest-based advertising via a CSRF-protected POST to
388-
<code>https://ads-are-awesome.example.com/optout</code>. The site author
389-
wishes to remove DOM-accessible data which might contain tracking information,
390-
but needs to ensure that the opt-out cookie which the user has just received
391-
isn’t wiped along with it.</p>
399+
400+
<div class="example" id="example-94c4a845"><a class="self-link" href="#example-94c4a845"></a>
401+
A user opts-out of interest-based advertising via a CSRF-protected POST to
402+
<code>https://ads-are-awesome.example.com/optout</code>. The site author
403+
wishes to remove DOM-accessible data which might contain tracking
404+
information, but needs to ensure that the opt-out cookie which the user has
405+
just received isn’t wiped along with it.
392406

393407

394-
<p>They can do so by sending the following HTTP header in the response, which
395-
includes all the types except for "<a data-link-type="dfn" href="#cookies">cookies</a>":</p>
408+
<p>They can do so by sending the following HTTP header in the response, which
409+
includes all the types except for "<a data-link-type="dfn" href="#cookies">cookies</a>":</p>
410+
396411

397-
398-
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: <a data-link-type="dfn" href="#domstorage">domStorage</a> <a data-link-type="dfn" href="#executioncontexts">executionContexts</a> <a data-link-type="dfn" href="#cache">cache</a>; <a data-link-type="dfn" href="#includesubdomains">includeSubdomains</a>
412+
413+
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: <a data-link-type="dfn" href="#domstorage">domStorage</a>; <a data-link-type="dfn" href="#executioncontexts">executionContexts</a>; <a data-link-type="dfn" href="#cache">cache</a>; <a data-link-type="dfn" href="#includesubdomains">includeSubdomains</a>
399414
</pre>
415+
416+
417+
</div>
400418

401419

402420
<h4 class="heading settled" data-level="1.1.4" id="example-killswitch"><span class="secno">1.1.4. </span><span class="content">Kill Switch</span><a class="self-link" href="#example-killswitch"></a></h4>
403421

404-
405-
<p>Super Secret Social Network’s developers learn that the site was vulnerable
406-
to cross-site scripting attacks which allowed malicious parties to inject
407-
arbitrary code into its origin. They fixed the site, and added a strong
408-
Content Security Policy <a data-link-type="biblio" href="#biblio-csp2">[CSP2]</a> to mitigate the risk going forward, but
409-
they can’t be entirely sure that clients are really back to a trustworthy
410-
state. Perhaps the attackers found a clever persistence mechanism?</p>
422+
423+
<div class="example" id="example-346b1576"><a class="self-link" href="#example-346b1576"></a>
424+
Super Secret Social Network’s developers learn that the site was vulnerable
425+
to cross-site scripting attacks which allowed malicious parties to inject
426+
arbitrary code into its origin. They fixed the site, and added a strong
427+
Content Security Policy <a data-link-type="biblio" href="#biblio-csp2">[CSP2]</a> to mitigate the risk going forward, but
428+
they can’t be entirely sure that clients are really back to a trustworthy
429+
state. Perhaps the attackers found a clever persistence mechanism?
411430

412431

413-
<p>They can reduce the risk of a persistent client-side XSS by sending the
414-
following HTTP header in a response to wipe out local sources of data:</p>
432+
<p>They can reduce the risk of a persistent client-side XSS by sending the
433+
following HTTP header in a response to wipe out local sources of data:</p>
434+
415435

416-
417-
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: *; <a data-link-type="dfn" href="#includesubdomains">includeSubdomains</a>
436+
437+
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: <a data-link-type="dfn" href="#">*</a>; <a data-link-type="dfn" href="#includesubdomains">includeSubdomains</a>
418438
</pre>
439+
419440

420441

421-
<p class="note" role="note">Note: Installing a Service Worker guarantees that a request will go out to
422-
a server every ~24 hours. That update ping would be a wonderful time to send
423-
a header like this one in case of catastophe. <a data-link-type="biblio" href="#biblio-service-workers">[SERVICE-WORKERS]</a></p>
442+
<p class="note" role="note">Note: Installing a Service Worker guarantees that a request will go out to
443+
a server every ~24 hours. That update ping would be a wonderful time to send
444+
a header like this one in case of catastophe. <a data-link-type="biblio" href="#biblio-service-workers">[SERVICE-WORKERS]</a></p>
445+
446+
447+
</div>
424448

425449

426450
<h3 class="heading settled" data-level="1.2" id="goals"><span class="secno">1.2. </span><span class="content">Goals</span><a class="self-link" href="#goals"></a></h3>
@@ -681,7 +705,7 @@ <h4 class="heading settled" data-level="2.1.6" id="wildcard-parameter"><span cla
681705
storage type parameters. That is:</p>
682706

683707

684-
<pre>Clear-Site-Data: *
708+
<pre><a data-link-type="dfn" href="#clear_site_data">Clear-Site-Data</a>: <a data-link-type="dfn" href="#">*</a>
685709
</pre>
686710

687711

‎specs/clear-site-data/index.src.html

Lines changed: 69 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -192,84 +192,93 @@ <h3 id="examples">Examples</h3>
192192

193193
<h4 id="example-signout">Signing Out</h4>
194194

195-
A user signs out of Super Secret Social Network via a CSRF-protected POST to
196-
<code>https://supersecretsocialnetwork.example.com/logout</code>, and the site
197-
author wishes to ensure that locally stored data is removed as a result.
195+
<div class="example">
196+
A user signs out of Super Secret Social Network via a CSRF-protected POST to
197+
<code>https://supersecretsocialnetwork.example.com/logout</code>, and the
198+
site author wishes to ensure that locally stored data is removed as a
199+
result.
198200

199-
They can do so by sending the following HTTP header in the response:
201+
They can do so by sending the following HTTP header in the response:
200202

201-
<pre>
202-
<a>Clear-Site-Data</a>: *
203-
</pre>
203+
<pre>
204+
<a>Clear-Site-Data</a>: <a>*</a>
205+
</pre>
206+
</div>
204207

205208
<h4 id="example-targeted">Targeted Clearing</h4>
206209

207-
A user signs out of Megacorp Inc.'s site via a CSRF-protected POST to
208-
<code>https://megacorp.example.com/logout</code>. Megacorp has a large number
209-
of services available as subdomains, so many that it's not entirely clear
210-
which of them would be safe to clear as a response to a logout action. One
211-
option would be to simply clear everything, and deal with the fallout.
212-
Megacorp's CEO, however, once lost hours and hours of progress in "Irate
213-
Ibexes" due to inadvertent site-data clearing, and so refuses to allow such
214-
a sweeping impact to the site's users.
215-
216-
The developers know, however, that the "Minus" application is certainly safe
217-
to clear out. They can target this specific subdomain by including a request
218-
to that subdomain as part of the logout landing page (ideally as a
219-
CORS-enabled, CSRF-protected POST):
210+
<div class="example">
211+
A user signs out of Megacorp Inc.'s site via a CSRF-protected POST to
212+
<code>https://megacorp.example.com/logout</code>. Megacorp has a large
213+
number of services available as subdomains, so many that it's not entirely
214+
clear which of them would be safe to clear as a response to a logout action.
215+
One option would be to simply clear everything, and deal with the fallout.
216+
Megacorp's CEO, however, once lost hours and hours of progress in "Irate
217+
Ibexes" due to inadvertent site-data clearing, and so refuses to allow such
218+
a sweeping impact to the site's users.
219+
220+
The developers know, however, that the "Minus" application is certainly safe
221+
to clear out. They can target this specific subdomain by including a request
222+
to that subdomain as part of the logout landing page (ideally as a
223+
CORS-enabled, CSRF-protected POST):
220224

221-
<pre>
222-
fetch("https://minus.megacorp.example.com/clear-site-data",
223-
{
224-
method: "POST",
225-
mode: "cors",
226-
headers: new Headers({
227-
"CSRF": "[<em>insert sekrit token here</em>]"
228-
})
229-
});
230-
</pre>
225+
<pre>
226+
fetch("https://minus.megacorp.example.com/clear-site-data",
227+
{
228+
method: "POST",
229+
mode: "cors",
230+
headers: new Headers({
231+
"CSRF": "[<em>insert sekrit token here</em>]"
232+
})
233+
});
234+
</pre>
231235

232-
That endpoint would return proper CORS headers in response to that request's
233-
preflight, and would return the following header for the actual request:
236+
That endpoint would return proper CORS headers in response to that request's
237+
preflight, and would return the following header for the actual request:
234238

235-
<pre>
236-
<a>Clear-Site-Data</a>: *; <a>includeSubdomains</a>
237-
</pre>
239+
<pre>
240+
<a>Clear-Site-Data</a>: <a>*</a>; <a>includeSubdomains</a>
241+
</pre>
242+
</div>
238243

239244
<h4 id="example-keepcookies">Keep Critical Cookies</h4>
240245

241-
A user opts-out of interest-based advertising via a CSRF-protected POST to
242-
<code>https://ads-are-awesome.example.com/optout</code>. The site author
243-
wishes to remove DOM-accessible data which might contain tracking information,
244-
but needs to ensure that the opt-out cookie which the user has just received
245-
isn't wiped along with it.
246+
<div class="example">
247+
A user opts-out of interest-based advertising via a CSRF-protected POST to
248+
<code>https://ads-are-awesome.example.com/optout</code>. The site author
249+
wishes to remove DOM-accessible data which might contain tracking
250+
information, but needs to ensure that the opt-out cookie which the user has
251+
just received isn't wiped along with it.
246252

247-
They can do so by sending the following HTTP header in the response, which
248-
includes all the types except for "<a>cookies</a>":
253+
They can do so by sending the following HTTP header in the response, which
254+
includes all the types except for "<a>cookies</a>":
249255

250-
<pre>
251-
<a>Clear-Site-Data</a>: <a>domStorage</a> <a>executionContexts</a> <a>cache</a>; <a>includeSubdomains</a>
252-
</pre>
256+
<pre>
257+
<a>Clear-Site-Data</a>: <a>domStorage</a>; <a>executionContexts</a>; <a>cache</a>; <a>includeSubdomains</a>
258+
</pre>
259+
</div>
253260

254261
<h4 id="example-killswitch">Kill Switch</h4>
255262

256-
Super Secret Social Network's developers learn that the site was vulnerable
257-
to cross-site scripting attacks which allowed malicious parties to inject
258-
arbitrary code into its origin. They fixed the site, and added a strong
259-
Content Security Policy [[CSP2]] to mitigate the risk going forward, but
260-
they can't be entirely sure that clients are really back to a trustworthy
261-
state. Perhaps the attackers found a clever persistence mechanism?
263+
<div class="example">
264+
Super Secret Social Network's developers learn that the site was vulnerable
265+
to cross-site scripting attacks which allowed malicious parties to inject
266+
arbitrary code into its origin. They fixed the site, and added a strong
267+
Content Security Policy [[CSP2]] to mitigate the risk going forward, but
268+
they can't be entirely sure that clients are really back to a trustworthy
269+
state. Perhaps the attackers found a clever persistence mechanism?
262270

263-
They can reduce the risk of a persistent client-side XSS by sending the
264-
following HTTP header in a response to wipe out local sources of data:
271+
They can reduce the risk of a persistent client-side XSS by sending the
272+
following HTTP header in a response to wipe out local sources of data:
265273

266-
<pre>
267-
<a>Clear-Site-Data</a>: *; <a>includeSubdomains</a>
268-
</pre>
274+
<pre>
275+
<a>Clear-Site-Data</a>: <a>*</a>; <a>includeSubdomains</a>
276+
</pre>
269277

270-
Note: Installing a Service Worker guarantees that a request will go out to
271-
a server every ~24 hours. That update ping would be a wonderful time to send
272-
a header like this one in case of catastrophe. [[SERVICE-WORKERS]]
278+
Note: Installing a Service Worker guarantees that a request will go out to
279+
a server every ~24 hours. That update ping would be a wonderful time to send
280+
a header like this one in case of catastrophe. [[SERVICE-WORKERS]]
281+
</div>
273282

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

@@ -456,7 +465,7 @@ <h4 id="wildcard-parameter">
456465
storage type parameters. That is:
457466

458467
<pre>
459-
Clear-Site-Data: *
468+
<a>Clear-Site-Data</a>: <a>*</a>
460469
</pre>
461470

462471
has the same meaning as:

0 commit comments

Comments
 (0)