@taxum/cookie/dist/jar.d.ts

Cookie jar for Taxum

import type { BinaryLike, CipherKey, KeyObject } from "node:crypto";
import { type HeaderMap, type HttpResponseParts, TO_HTTP_RESPONSE_PARTS, type ToHttpResponseParts } from "@taxum/core/http";
import { Cookie } from "./cookie.js";
import { PrivateJar } from "./private.js";
import { SignedJar } from "./signed.js";
/**
 * 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"));
 * ```
 */
export declare class CookieJar implements ToHttpResponseParts {
    private originalCookies;
    private deltaCookies;
    /**
     * Creates a new {@link CookieJar}.
     *
     * You can optionally provide an array of {@link Cookie}s to initialize the
     * jar with. These cookies must be raw request cookies.
     */
    constructor(originalCookies?: Cookie[]);
    /**
     * Creates a {@link CookieJar} from a {@link HeaderMap}.
     */
    static fromHeaders(headers: HeaderMap): CookieJar;
    /**
     * Returns a {@link 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.
     *
     * @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");
     * ```
     */
    signed(key: BinaryLike | KeyObject): SignedJar;
    /**
     * Returns a {@link 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.
     *
     * @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");
     * ```
     */
    private(key: CipherKey): PrivateJar;
    /**
     * Returns a cookie inside this jar with the name `name`.
     *
     * If the cookie is not found, returns `null`.
     */
    get(name: string): Cookie | null;
    /**
     * Adds a {@link Cookie} to this jar.
     *
     * If a cookie with the same name already exists, it will be replaced.
     */
    add(cookie: Cookie): void;
    /**
     * Removes a {@link 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.
     */
    remove(cookie: Cookie): void;
    /**
     * Returns an iterator over all the cookies present in this jar.
     */
    [Symbol.iterator](): IterableIterator<Cookie>;
    [TO_HTTP_RESPONSE_PARTS](res: HttpResponseParts): void;
}