From 11c662b08b38a409009a07f646ca92f09542adb3 Mon Sep 17 00:00:00 2001 From: Brad Ito Date: Thu, 30 Jan 2020 13:39:24 -0800 Subject: [PATCH 1/3] Updating context.md with the latest cookies opts Copying from the source document of the cookies module. In particular, adding in documentation of the sameSite attribute --- docs/api/context.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/api/context.md b/docs/api/context.md index 30b5226c4..6887efba7 100644 --- a/docs/api/context.md +++ b/docs/api/context.md @@ -78,14 +78,15 @@ Koa uses the [cookies](https://github.com/pillarjs/cookies) module where options Set cookie `name` to `value` with `options`: - - `maxAge` a number representing the milliseconds from Date.now() for expiry - - `signed` sign the cookie value - - `expires` a `Date` for cookie expiration - - `path` cookie path, `'/'` by default - - `domain` cookie domain - - `secure` secure cookie - - `httpOnly` server-accessible cookie, __true__ by default - - `overwrite` a boolean indicating whether to overwrite previously set cookies of the same name (__false__ by default). If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie. +* `maxAge`: a number representing the milliseconds from `Date.now()` for expiry +* `expires`: a `Date` object indicating the cookie's expiration date (expires at the end of session by default). +* `path`: a string indicating the path of the cookie (`/` by default). +* `domain`: a string indicating the domain of the cookie (no default). +* `secure`: a boolean indicating whether the cookie is only to be sent over HTTPS (`false` by default for HTTP, `true` by default for HTTPS). [Read more about this option](https://github.com/pillarjs/cookies#secure-cookies). +* `httpOnly`: a boolean indicating whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript (`true` by default). +* `sameSite`: a boolean or string indicating whether the cookie is a "same site" cookie (`false` by default). This can be set to `'strict'`, `'lax'`, or `true` (which maps to `'strict'`). +* `signed`: a boolean indicating whether the cookie is to be signed (`false` by default). If this is true, another cookie of the same name with the `.sig` suffix appended will also be sent, with a 27-byte url-safe base64 SHA1 value representing the hash of _cookie-name_=_cookie-value_ against the first [Keygrip](https://www.npmjs.com/package/keygrip) key. This signature key is used to detect tampering the next time a cookie is received. +* `overwrite`: a boolean indicating whether to overwrite previously set cookies of the same name (`false` by default). If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie. Koa uses the [cookies](https://github.com/pillarjs/cookies) module where options are simply passed. From a3ba584483e56c256d9f20684986684bf4fd969d Mon Sep 17 00:00:00 2001 From: Brad Ito Date: Thu, 30 Jan 2020 13:45:28 -0800 Subject: [PATCH 2/3] adding in documentation of sameSite:"none" The cookies source documentation is missing this, but it supports the value of "none" for the sameSite option. passing along this enhancement to koa's documentation --- docs/api/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/context.md b/docs/api/context.md index 6887efba7..4bc8e61fc 100644 --- a/docs/api/context.md +++ b/docs/api/context.md @@ -84,7 +84,7 @@ Koa uses the [cookies](https://github.com/pillarjs/cookies) module where options * `domain`: a string indicating the domain of the cookie (no default). * `secure`: a boolean indicating whether the cookie is only to be sent over HTTPS (`false` by default for HTTP, `true` by default for HTTPS). [Read more about this option](https://github.com/pillarjs/cookies#secure-cookies). * `httpOnly`: a boolean indicating whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript (`true` by default). -* `sameSite`: a boolean or string indicating whether the cookie is a "same site" cookie (`false` by default). This can be set to `'strict'`, `'lax'`, or `true` (which maps to `'strict'`). +* `sameSite`: a boolean or string indicating whether the cookie is a "same site" cookie (`false` by default). This can be set to `'strict'`, `'lax'`, `'none'`, or `true` (which maps to `'strict'`). * `signed`: a boolean indicating whether the cookie is to be signed (`false` by default). If this is true, another cookie of the same name with the `.sig` suffix appended will also be sent, with a 27-byte url-safe base64 SHA1 value representing the hash of _cookie-name_=_cookie-value_ against the first [Keygrip](https://www.npmjs.com/package/keygrip) key. This signature key is used to detect tampering the next time a cookie is received. * `overwrite`: a boolean indicating whether to overwrite previously set cookies of the same name (`false` by default). If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie. From 5fe1b726647f36126a8e793ec2856596fde0a085 Mon Sep 17 00:00:00 2001 From: Brad Ito Date: Fri, 7 Feb 2020 13:51:50 -0600 Subject: [PATCH 3/3] Update docs/api/context.md with period Co-Authored-By: imed jaberi --- docs/api/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/context.md b/docs/api/context.md index 4bc8e61fc..bf3a2dd03 100644 --- a/docs/api/context.md +++ b/docs/api/context.md @@ -78,7 +78,7 @@ Koa uses the [cookies](https://github.com/pillarjs/cookies) module where options Set cookie `name` to `value` with `options`: -* `maxAge`: a number representing the milliseconds from `Date.now()` for expiry +* `maxAge`: a number representing the milliseconds from `Date.now()` for expiry. * `expires`: a `Date` object indicating the cookie's expiration date (expires at the end of session by default). * `path`: a string indicating the path of the cookie (`/` by default). * `domain`: a string indicating the domain of the cookie (no default).