/** * A session store in browser cookies, so two sites under one parent domain share one sign-in: * * snout(url, key, { auth: { storage: cookieStorage({ domain: '.example.com' }) } }) * * The format, which every SnoutData site reads and writes, so a visitor signed in on one is signed * in on the others: * * - A stored value is `base64-` followed by the base64url of its UTF-8 bytes, without padding. * A value without that prefix (written before it existed) is read as it is. * - A cookie's value is URI-encoded on the wire. When the encoded value is at most * `COOKIE_VALUE_LIMIT` characters it is one cookie, named as the key. Otherwise it is cut into * pieces named `.0`, `.1`, …, each at most that many characters once encoded, and * never cut through a character (so never through a `%XX` escape either). * - Reading takes the cookie named as the key when there is one, or else joins `.0`, * `.1`, … in order up to the first missing number. Pieces that do not decode to JSON * came from two different writes, and read as no session at all. * - Writing a shorter value clears the numbered pieces it no longer uses. A clear at a parent * domain also clears the host-only copy, which a site that once stored host-only would * otherwise bring back after sign-out. * * The limit leaves room under a browser's 4,096 bytes per cookie for the name and attributes. */ import type { SessionStorage } from './auth.js'; export interface CookieOptions { /** `.example.com` to share between subdomains. Leave unset for host-only. */ domain?: string; path?: string; sameSite?: 'lax' | 'strict' | 'none'; secure?: boolean; /** Seconds. 400 days by default, the most a browser honours. */ maxAge?: number; } /** What `document` offers; a test passes its own. */ export interface CookieJar { cookie: string; } /** The most characters a cookie's URI-encoded value may hold before the value is cut into pieces. */ export declare const COOKIE_VALUE_LIMIT = 3180; /** One cookie to write: a name and its value before URI encoding. */ export interface CookiePiece { name: string; value: string; } /** * Lays a value out as cookies. A value whose encoding fits in `limit` is one cookie named `key`; * a longer one is packed, a whole character at a time, into `.0`, `.1`, … with each * piece's encoding filled as far as `limit` allows. Measuring each character's own encoding * is what keeps a `%XX` escape, and a character of several bytes, inside one piece. */ export declare function splitCookieValue(key: string, value: string, limit?: number): CookiePiece[]; export declare function cookieStorage(options?: CookieOptions, jar?: CookieJar): SessionStorage;