Update samesite content

6-data-storage/01-cookie/article.md

@@ -2,17 +2,17 @@
 
 Cookies are small strings of data that are stored directly in the browser. They are a part of the HTTP protocol, defined by the [RFC 6265](https://tools.ietf.org/html/rfc6265) specification.
 
-Cookies are usually set by a web-server using the response `Set-Cookie` HTTP-header. Then, the browser automatically adds them to (almost) every request to the same domain using the `Cookie` HTTP-header.
+Cookies are usually set by a web server using the response `Set-Cookie` HTTP header. Then, the browser automatically adds them to (almost) every request to the same domain using the `Cookie` HTTP header.
 
 One of the most widespread use cases is authentication:
 
-1. Upon sign-in, the server uses the `Set-Cookie` HTTP-header in the response to set a cookie with a unique "session identifier".
-2. Next time the request is sent to the same domain, the browser sends the cookie over the net using the `Cookie` HTTP-header.
+1. Upon sign-in, the server uses the `Set-Cookie` HTTP header in the response to set a cookie with a unique "session identifier".
+2. Next time the request is sent to the same domain, the browser sends the cookie over the net using the `Cookie` HTTP header.
 3. So the server knows who made the request.
 
 We can also access cookies from the browser, using `document.cookie` property.
 
-There are many tricky things about cookies and their options. In this chapter, we'll cover them in detail.
+There are many tricky things about cookies and their attributes. In this chapter, we'll cover them in detail.
 
 ## Reading from document.cookie
 
@@ -73,9 +73,9 @@ There are a few limitations:
 - The total number of cookies per domain is limited to around 20+, the exact limit depends on the browser.
 ```
 
-Cookies have several options, many of which are important and should be set.
+Cookies have several attributes, many of which are important and should be set.
 
-The options are listed after `key=value`, delimited by `;`, like this:
+The attributes are listed after `key=value`, delimited by `;`, like this:
 
 ```js run
 document.cookie = "user=John; path=/; expires=Tue, 19 Jan 2038 03:14:07 GMT"
@@ -105,7 +105,7 @@ alert(document.cookie); // no user
 
 ...But this can be changed. If we'd like to allow subdomains like `forum.site.com` to get a cookie set at `site.com`, that's possible.
 
-For that to happen, when setting a cookie at `site.com`, we should explicitly set the `domain` option to the root domain: `domain=site.com`. Then all subdomains will see such a cookie.
+For that to happen, when setting a cookie at `site.com`, we should explicitly set the `domain` attribute to the root domain: `domain=site.com`. Then all subdomains will see such a cookie.
 
 For example:
 
@@ -124,23 +124,23 @@ alert(document.cookie); // has cookie user=John
 Historically, `domain=.site.com` (with a dot before `site.com`) used to work the same way, allowing access to the cookie from subdomains. Leading dots in domain names are now ignored, but some browsers may decline to set the cookie containing such dots.
 ```
 
-To summarize, the `domain` option allows to make a cookie accessible at subdomains.
+To summarize, the `domain` attribute allows to make a cookie accessible at subdomains.
 
 ## path
 
 - **`path=/mypath`**
 
-The url path prefix must be absolute. It makes the cookie accessible for pages under that path. By default, it's the current path.
+The URL path prefix must be absolute. It makes the cookie accessible for pages under that path. By default, it's the current path.
 
 If a cookie is set with `path=/admin`, it's visible on pages `/admin` and `/admin/something`, but not at `/home`, `/home/admin` or `/`.
 
-Usually, we should set `path` to the root: `path=/` to make the cookie accessible from all website pages. If this option is not set the default is calculated using [this method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#path_default_value).
+Usually, we should set `path` to the root: `path=/` to make the cookie accessible from all website pages. If this attribute is not set the default is calculated using [this method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#path_default_value).
 
 ## expires, max-age
 
-By default, if a cookie doesn't have one of these options, it disappears when the browser/tab is closed. Such cookies are called "session cookies"
+By default, if a cookie doesn't have one of these attributes, it disappears when the browser/tab is closed. Such cookies are called "session cookies"
 
-To let cookies survive a browser close, we can set either the `expires` or `max-age` option. `max-Age` has precedence if both are set.
+To let cookies survive a browser close, we can set either the `expires` or `max-age` attribute. `max-Age` has precedence if both are set.
 
 - **`expires=Tue, 19 Jan 2038 03:14:07 GMT`**
 
@@ -181,7 +181,7 @@ The cookie should be transferred only over HTTPS.
 
 That is, cookies are domain-based, they do not distinguish between the protocols.
 
-With this option, if a cookie is set by `https://site.com`, then it doesn't appear when the same site is accessed by HTTP, as `http://site.com`. So if a cookie has sensitive content that should never be sent over unencrypted HTTP, the `secure` flag is the right thing.
+With this attribute, if a cookie is set by `https://site.com`, then it doesn't appear when the same site is accessed by HTTP, as `http://site.com`. So if a cookie has sensitive content that should never be sent over unencrypted HTTP, the `secure` flag is the right thing.
 
 ```js
 // assuming we're on https:// now
@@ -191,7 +191,7 @@ document.cookie = "user=John; secure";
 
 ## samesite
 
-That's another security attribute `samesite`. It's designed to protect from so-called XSRF (cross-site request forgery) attacks.
+This is another security attribute `samesite`. It's designed to protect from so-called XSRF (cross-site request forgery) attacks.
 
 To understand how it works and when it's useful, let's take a look at XSRF attacks.
 
@@ -205,15 +205,15 @@ The browser sends cookies every time you visit the site `bank.com`, even if the
 
 ![](cookie-xsrf.svg)
 
-That's a so-called "Cross-Site Request Forgery" (in short, XSRF) attack.
+This is a so-called "Cross-Site Request Forgery" (in short, XSRF) attack.
 
 Real banks are protected from it of course. All forms generated by `bank.com` have a special field, a so-called "XSRF protection token", that an evil page can't generate or extract from a remote page. It can submit a form there, but can't get the data back. The site `bank.com` checks for such a token in every form it receives.
 
 Such a protection takes time to implement though. We need to ensure that every form has the required token field, and we must also check all requests.
 
-### Enter cookie samesite option
+### Use cookie samesite attribute
 
-The cookie `samesite` option provides another way to protect from such attacks, that (in theory) should not require "xsrf protection tokens".
+The cookie `samesite` attribute provides another way to protect from such attacks, that (in theory) should not require "xsrf protection tokens".
 
 It has two possible values:
 
@@ -223,9 +223,9 @@ A cookie with `samesite=strict` is never sent if the user comes from outside the
 
 In other words, whether a user follows a link from their email, submits a form from `evil.com`, or does any operation that originates from another domain, the cookie is not sent.
 
-If authentication cookies have the `samesite` option, then an XSRF attack has no chance of succeeding, because a submission from `evil.com` comes without cookies. So `bank.com` will not recognize the user and will not proceed with the payment.
+If authentication cookies have the `samesite=strict` attribute, then an XSRF attack has no chance of succeeding, because a submission from `evil.com` comes without cookies. So `bank.com` will not recognize the user and will not proceed with the payment.
 
-The protection is quite reliable. Only operations that come from `bank.com` will send the `samesite` cookie, e.g. a form submission from another page at `bank.com`.
+The protection is quite reliable. Only operations that come from `bank.com` will send the `samesite=strict` cookie, e.g. a form submission from another page at `bank.com`.
 
 Although, there's a small inconvenience.
 
@@ -246,36 +246,36 @@ A `samesite=lax` cookie is sent if both of these conditions are true:
 
 2. The operation performs a top-level navigation (changes URL in the browser address bar).
 
-    That's usually true, but if the navigation is performed in an `<iframe>`, then it's not top-level. Also, JavaScript methods for network requests do not perform any navigation, hence they don't fit.
+    This is usually true, but if the navigation is performed in an `<iframe>`, then it is not top-level. Additionally, JavaScript methods for network requests do not perform any navigation.
 
 So, what `samesite=lax` does, is to allow the most common "go to URL" operation to have cookies. E.g. opening a website link from notes that satisfy these conditions.
 
 But anything more complicated, like a network request from another site or a form submission, loses cookies.
 
 If that's fine for you, then adding `samesite=lax` will probably not break the user experience and add protection.
 
-Overall, `samesite` is a great option.
+Overall, `samesite` is a great attribute.
 
 There's a drawback:
 
 - `samesite` is ignored (not supported) by very old browsers, the year 2017 or so.
 
 **So if we solely rely on `samesite` to provide protection, then old browsers will be vulnerable.**
 
-But we surely can use `samesite` together with other protection measures, like xsrf tokens, to add layer of defence and then, in the future, when old browsers die out, we'll probably be able to drop xsrf tokens.
+But we surely can use `samesite` together with other protection measures, like xsrf tokens, to add a layer of defence and then, in the future, when old browsers die out, we'll probably be able to drop xsrf tokens.
 
 ## httpOnly
 
-This option has nothing to do with JavaScript, but we have to mention it for completeness.
+This attribute has nothing to do with JavaScript, but we have to mention it for completeness.
 
-The web-server uses the `Set-Cookie` header to set a cookie. Also, it may set the `httpOnly` option.
+The web server uses the `Set-Cookie` header to set a cookie. Also, it may set the `httpOnly` attribute.
 
-This option forbids any JavaScript access to the cookie. We can't see such a cookie or manipulate it using `document.cookie`.
+This attribute forbids any JavaScript access to the cookie. We can't see such a cookie or manipulate it using `document.cookie`.
 
 This is used as a precautionary measure, to protect from certain attacks when a hacker injects his own JavaScript code into a page and waits for a user to visit that page. That shouldn't be possible at all, hackers should not be able to inject their code into our site, but there may be bugs that let them do it.
 
 
-Normally, if such a thing happens, and a user visits a web-page with hacker's JavaScript code, then that code executes and gains access to `document.cookie` with user cookies containing authentication information. That's bad.
+Normally, if such a thing happens, and a user visits a web-page with a hacker's JavaScript code, then that code executes and gains access to `document.cookie` with user cookies containing authentication information. That's bad.
 
 But if a cookie is `httpOnly`, then `document.cookie` doesn't see it, so it is protected.
 
@@ -306,30 +306,30 @@ Here `new RegExp` is generated dynamically, to match `; name=<value>`.
 
 Please note that a cookie value is encoded, so `getCookie` uses a built-in `decodeURIComponent` function to decode it.
 
-### setCookie(name, value, options)
+### setCookie(name, value, attributes)
 
 Sets the cookie's `name` to the given `value` with `path=/` by default (can be modified to add other defaults):
 
 ```js run
-function setCookie(name, value, options = {}) {
+function setCookie(name, value, attributes = {}) {
 
-  options = {
+  attributes = {
     path: '/',
     // add other defaults here if necessary
-    ...options
+    ...attributes
   };
 
-  if (options.expires instanceof Date) {
-    options.expires = options.expires.toUTCString();
+  if (attributes.expires instanceof Date) {
+    attributes.expires = attributes.expires.toUTCString();
   }
 
   let updatedCookie = encodeURIComponent(name) + "=" + encodeURIComponent(value);
 
-  for (let optionKey in options) {
-    updatedCookie += "; " + optionKey;
-    let optionValue = options[optionKey];
-    if (optionValue !== true) {
-      updatedCookie += "=" + optionValue;
+  for (let attributeKey in attributes) {
+    updatedCookie += "; " + attributeKey;
+    let attributeValue = attributes[attributeKey];
+    if (attributeValue !== true) {
+      updatedCookie += "=" + attributeValue;
     }
   }
 
@@ -353,7 +353,7 @@ function deleteCookie(name) {
 ```
 
 ```warn header="Updating or deleting must use same path and domain"
-Please note: when we update or delete a cookie, we should use exactly the same path and domain options as when we set it.
+Please note: when we update or delete a cookie, we should use exactly the same path and domain attributes as when we set it.
 ```
 
 Together: [cookie.js](cookie.js).
@@ -380,7 +380,7 @@ For instance:
 
 Third-party cookies are traditionally used for tracking and ads services, due to their nature. They are bound to the originating domain, so `ads.com` can track the same user between different sites, if they all access it.
 
-Naturally, some people don't like being tracked, so browsers allow to disable such cookies.
+Naturally, some people don't like being tracked, so browsers allow them to disable such cookies.
 
 Also, some modern browsers employ special policies for such cookies:
 - Safari does not allow third-party cookies at all.
@@ -395,28 +395,28 @@ If a script sets a cookie, then no matter where the script came from -- the cook
 
 ## Appendix: GDPR
 
-This topic is not related to JavaScript at all, just something to keep in mind when setting cookies.
+This topic is not related to JavaScript at all, it is just something to keep in mind when setting cookies.
 
-There's a legislation in Europe called GDPR, that enforces a set of rules for websites to respect the users' privacy. One of these rules is to require an explicit permission for tracking cookies from the user.
+There's a legislation in Europe called GDPR, that enforces a set of rules for websites to respect the users' privacy. One of these rules is to require explicit permission for tracking cookies from the user.
 
 Please note, that's only about tracking/identifying/authorizing cookies.
 
 So, if we set a cookie that just saves some information, but neither tracks nor identifies the user, then we are free to do it.
 
-But if we are going to set a cookie with an authentication session or a tracking id, then a user must allow that.
+But if we are going to set a cookie with an authentication session or a tracking ID, then a user must allow that.
 
-Websites generally have two variants of following GDPR. You must have seen them both already in the web:
+Websites generally have two variants of complying with GDPR. You are likely to have seen them both on the web:
 
 1. If a website wants to set tracking cookies only for authenticated users.
 
     To do so, the registration form should have a checkbox like "accept the privacy policy" (that describes how cookies are used), the user must check it, and then the website is free to set auth cookies.
 
 2. If a website wants to set tracking cookies for everyone.
 
-    To do so legally, a website shows a modal "splash screen" for newcomers, and requires them to agree to the cookies. Then the website can set them and let people see the content. That can be disturbing for new visitors though. No one likes to see such "must-click" modal splash screens instead of the content. But GDPR requires an explicit agreement.
+    To do so legally, a website shows a modal "splash screen" for newcomers and requires them to agree to the cookies. Then the website can set them and let people see the content. That can be disturbing for new visitors though. No one likes to see such "must-click" modal splash screens instead of the content. But GDPR requires an explicit agreement.
 
 
-GDPR is not only about cookies, it's about other privacy-related issues too, but that's too much beyond our scope.
+GDPR is not only about cookies, it is about other privacy-related issues too, but that is beyond our scope.
 
 
 ## Summary
@@ -426,13 +426,13 @@ GDPR is not only about cookies, it's about other privacy-related issues too, but
 - Name/value must be encoded.
 - One cookie may not exceed 4KB in size. The number of cookies allowed on a domain is around 20+ (varies by browser).
 
-Cookie options:
+Cookie attributes:
 - `path=/`, by default current path, makes the cookie visible only under that path.
 - `domain=site.com`, by default a cookie is visible on the current domain only. If the domain is set explicitly, the cookie becomes visible on subdomains.
-- `expires` or `max-age` sets the cookie expiration time. Without them the cookie dies when the browser is closed.
+- `expires` or `max-age` sets the cookie expiration time. Without them, the cookie dies when the browser is closed.
 - `secure` makes the cookie HTTPS-only.
 - `samesite` forbids the browser to send the cookie with requests coming from outside the site. This helps to prevent XSRF attacks.
 
 Additionally:
-- Third-party cookies may be forbidden by the browser, e.g. Safari does that by default.
+- The browser may forbid third-party cookies, e.g. Safari does that by default. There is also work in progress to implement this in Chrome.
 - When setting a tracking cookie for EU citizens, GDPR requires to ask for permission.