Taxum

Appearance

Taxum / @taxum/cookie / CookieJar

Class: CookieJar ​

Defined in: jar.ts:32

A collection of cookies that tracks its modifications.

A CookieJar provides storage for any number of cookies. Any changes made to the jar are tracked; when serialized to response parts, the modified cookies are added to the response headers.

Example ​

ts
import { Cookie, CookieJar } from "@taxum/cookie";

const jar = new CookieJar();
jar.add(new Cookie("foo", "bar"));

Implements ​

Constructors ​

Constructor ​

new CookieJar(originalCookies?): CookieJar

Defined in: jar.ts:42

Creates a new CookieJar.

You can optionally provide an array of Cookies to initialize the jar with. These cookies must be raw request cookies.

Parameters ​

originalCookies? ​

Cookie[]

Returns ​

CookieJar

Methods ​

[iterator]() ​

[iterator](): IterableIterator<Cookie>

Defined in: jar.ts:176

Returns an iterator over all the cookies present in this jar.

Returns ​

IterableIterator<Cookie>

[TO_HTTP_RESPONSE_PARTS]() ​

[TO_HTTP_RESPONSE_PARTS](res): void

Defined in: jar.ts:193

Parameters ​

res ​

HttpResponseParts

Returns ​

void

Implementation of ​

ToHttpResponseParts.[TO_HTTP_RESPONSE_PARTS]

add() ​

add(cookie): void

Defined in: jar.ts:149

Adds a Cookie to this jar.

If a cookie with the same name already exists, it will be replaced.

Parameters ​

Cookie

Returns ​

void

get() ​

get(name): null | Cookie

Defined in: jar.ts:139

Returns a cookie inside this jar with the name name.

If the cookie is not found, returns null.

Parameters ​

name ​

string

Returns ​

null | Cookie

private() ​

private(key): PrivateJar

Defined in: jar.ts:130

Returns a PrivateJar with this as its parent jar using the key key to verify/decrypt cookies from the child jar.

Any retrievals from the child jar will be made from the parent jar.

Parameters ​

key ​

CipherKey

Returns ​

PrivateJar

Example ​

ts
import { assert } from "node:assert/strict";
import { generateKey } from "node:crypto";
import { Cookie, CookieJar } from "@taxum/cookie";

const jar = new CookieJar();

// Generate a secure key.
const key = generateKey("aes", { length: 256 });

// Add a private (signed and encrypted) cookie.
jar.private(key).add(new Cookie("private", "text"));

// The cookie's contents are encrypted.
assert.notEqual(jar.get("private")?.value, "text");

// They can be decrypted and verified through the child jar.
assert.equal(jar.private(key).get("private")?.value, "text");

// A tampered with cookie does not validate but still exists.
jar.add(new Cookie("private", "tampered"));
assert.equal(jar.private(key).get("private"), null);
assert.equal(jar.get("private")?.value, "tampered");

remove() ​

remove(cookie): void

Defined in: jar.ts:165

Removes a Cookie from this jar.

If an original cookie with the same name as cookie is present in the jar, a removal cookie will be present in the response. To properly generate a removal cookie, cookie must contain the same path and domain as the cookie that was initially set.

A "removal" cookie is a cookie that has the same name as the original cookie but has an empty value, a max-age of 0, and an expiration date far in the past.

Parameters ​

Cookie

Returns ​

void

signed() ​

signed(key): SignedJar

Defined in: jar.ts:94

Returns a SignedJar with this as its parent jar using the key key to verify cookies retrieved from the child jar.

Any retrievals from the child jar will be made from the parent jar.

Parameters ​

key ​

BinaryLike | KeyObject

Returns ​

SignedJar

Example ​

ts
import { assert } from "node:assert/strict";
import { generateKey } from "node:crypto";
import { Cookie, CookieJar } from "@taxum/cookie";

const jar = new CookieJar();

// Generate a secure key.
const key = generateKey("hmac", { length: 512 });

// Add a signed cookie.
jar.signed(key).add(new Cookie("signed", "text"));

// The cookie's contents are signed but still plaintext.
assert.notEqual(jar.get("signed")?.value, "text");
assert.match(jar.get("signed")?.value, /text/);

// They can be verified through the child jar.
assert.equal(jar.signed(key).get("signed")?.value, "text");

// A tampered with cookie does not validate but still exists.
jar.add(new Cookie("signed", "tampered"));
assert.equal(jar.signed(key).get("signed"), null);
assert.equal(jar.get("signed")?.value, "tampered");

fromHeaders() ​

static fromHeaders(headers): CookieJar

Defined in: jar.ts:51

Creates a CookieJar from a HeaderMap.

Parameters ​

headers ​

HeaderMap

Returns ​

CookieJar