# @vs-org/cookie
> This is simple cookie helper for handling cookie operations like create cookie, get cookie (signed or unsigned), sign cookie with secret, verify cookie signature, parse cookies from cookie string
Latest version **0.0.10** (published 2022-09-14) · MIT license · 0 weekly downloads
## Install
```sh
npm install @vs-org/cookie
pnpm add @vs-org/cookie
yarn add @vs-org/cookie
bun add @vs-org/cookie
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.0.10 |
| Published | 2022-09-14 |
| First published | 2022-09-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 40.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Vaibhav Sarwade |
| Maintainers | vs-org |
| Keywords | cookie parser, cookie handler, cookies, node js cookies, express cookie, vs cookie, vs-org cookie |
## Links
- npm: https://www.npmjs.com/package/@vs-org/cookie
- Repository: https://github.com/vaibhav-sarwade-404/vs-cookie
- Homepage: https://github.com/vaibhav-sarwade-404/vs-cookie#readme
- Issues: https://github.com/vaibhav-sarwade-404/vs-cookie/issues
- npm.io page: https://npm.io/package/@vs-org/cookie
## Recent versions
- 0.0.10 (latest) — 2022-09-14
- 0.0.9 — 2022-09-13
- 0.0.8 — 2022-09-12
- 0.0.7 — 2022-09-12
- 0.0.6 — 2022-09-09
- 0.0.5 — 2022-09-09
- 0.0.4 — 2022-09-09
- 0.0.3 — 2022-09-09
- 0.0.2 — 2022-09-09
- 0.0.1 — 2022-09-08
## README
# vs-cookie
This is simple cookie helper for handling cookie operations.
## Usage
1. Create cookie
Note using this function depends on browser, if combination is used that is not validated but also not accepted by browser then cookie will not be saved. Make sure of options before using this function.
```
const { createCookie } = require("@vs-org/cookie");
const cookie = createCookie({
name: "test",
value: "test"
});
console.log(cookie); // test=test;Priority=Medium
```
2. Get unsigned cookie value
```
const { getCookie } = require("@vs-org/cookie");
const cookie = getCookie("test1=test1; test=test", "test");
console.log(cookie); // "test"
```
3. Get signed cookie value
```
const { getCookie } = require("@vs-org/cookie");
const cookie = getCookie("test1=test1; test=test.hWtzMM7E4KTirRm3N8GZ4DB5E1b9j4DVtMYh4zkwvQ", "test", {secret: "This is cookie signing secret"});
console.log(cookie); // "test%3AhWtzMM7E4KTirRm3N8GZ4DB5E1b9j4DVtMYh4zkwvQ"
```
4. Parse all cookies
```
const { parse } = require("@vs-org/cookie");
const parsedCookies = parse("test1=test1; test=test%3AhWtzMM7E4KTirRm3N8GZ4DB5E1b9j4DVtMYh4zkwvQ");
console.log(parsedCookies); // { test1: 'test1', test: 'test%3AhWtzMM7E4KTirRm3N8GZ4DB5E1b9j4DVtMYh4zkwvQ' }
```
5. sign cookie
```
const { sign } = require("@vs-org/cookie");
const signedCookie = sign("cookieValue","This is cookie signing secret");
console.log(signedCookie); // cookieValue%3A2V92ZahIZBNWU5aJSVZBeFNSMfNTqOl2crexQyKo
```
6. sign cookie but use different separtor
a) Package uses `:` as default separator for cookie and cookie signature.
b) If application has cookies containing `:` then `separator` can be passed in option to use it to sign cookie. Make sure same separator is used while verifying
```
const { sign } = require("@vs-org/cookie");
const signedCookie = sign("Cookie :test value", "This is cookie signing secret", { separator: "-" });
console.log(signedCookie); // Cookie%20%3Atest%20value-3KV68YGLG0GrgscHSlFoRyDgvzxaN3o0gT3oBTr7EM
```
7. verify cookie signature
```
const { verify } = require("@vs-org/cookie");
const isValidCookie1 = verify("cookieValue%3A2V92ZahIZBNWU5aJSVZBeFNSMfNTqOl2crexQyKo","This is cookie signing secret");
console.log(isValidCookie1); // true
const isValidCookie2 = verify("cookieValue%3Aabcdefg","This is cookie signing secret");
console.log(isValidCookie2); // false
```
8. verify cookie signature with different separator
a) Package uses `:` as default separator for cookie and cookie signature.
b) If application has signed cookies with different separator then `separator` can be passed in option which will be used for verifying signature.
```
const { verify } = require("@vs-org/cookie");
const isValidCookie1 = verify("Cookie%20%3Atest%20value-3KV68YGLG0GrgscHSlFoRyDgvzxaN3o0gT3oBTr7EM","This is cookie signing secret", { separator: "-" });
console.log(isValidCookie1); // true
```
## Options
1. Create cookie option
| option | type / accepted values | Description |
| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Cookie name, should not contain `( ) < > @ , ; : " /[ ]?={}` or spaces |
| `value` | string | Cookie value |
| `encode` | function | By default value will be encoded with `encodeURIComponent` but if custom encoding is required this option can accept encoding function. Note encoding function should always return `string` or else there will unexpected behaviours |
| `Path` | string | Cookie path, by default current path will be assigned by browser |
| `Domain` | string | Cookie domain, by default current domain will be assigned by browser |
| `HttpOnly` | boolean | This attribute indicates, if cookie will accessible to javascript or not |
| `Max-Age` | number | Cookie expiry in seconds |
| `Prefix` | `__Secure- , __Host-` | Cookie prefix can be used only when secure is set as true and for HTTPs origins. `__Secure-` (this prefix cookies must be set with secure flag and from HTTPs origin), `__Host-` (can have only path as `/` and cannot have domain. Package will throw error if domain and path is provided along side this option) |
| `Priority` | `Hight, Mediym, Low` | Prioriy can be set in Chrome browser only as of today. It helps browser decides cookie priority in order to strip cookies in case of limit exceeds |
| `Secure` | boolean | only send cookies with HTTPS and not HTTP |
| `SameSite` | `true, Strict, Lax, None` | Cookies used for storing sensetive information like authentication / authenticated session should have short lifetime with SameSite as "Strict" or "Lax" |
## VS Cookie function signatures
| Name | Function signature |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `createCookie` | `(cookieOption: VsCookieOption) => string \| never` |
| `getCookie` | `(cookies: string, cookieName: string, options?: {decode?: Function; secret?: string; separator?: string;}) => string \| never` |
| `parse` | `(cookies: string, decode: Function = decodeURIComponent) => object \| never` |
| `sign` | `(cookie: string, secret: string, options: { separator?: string; encode?: Function }) => string \| never` |
| `verify` | `(cookie: string, secret: string, options: { separator?: string; decode?: Function }) => boolean \| never` |
## Note
This package is experimental and not production ready. Should only be used for developement or POC. Also this package is not actively maintained.
## License
MIT (see [LICENSE](https://github.com/vaibhav-sarwade-404/vs-cookie/blob/main/LICENSE))
---
_Source: https://npm.io/package/@vs-org/cookie · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._