iron-session 8.0.3 → 9.0.0-beta.0

package/dist/index.d.ts

@@ -1,115 +1,294 @@
-import * as http from 'http';
-import { CookieSerializeOptions } from 'cookie';
-
+import { SetCookie } from "cookie";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/core.d.ts
 type PasswordsMap = Record<string, string>;
 type Password = PasswordsMap | string;
+type RequestType = IncomingMessage | Request;
+type ResponseType = Response | ServerResponse;
 /**
  * {@link https://wicg.github.io/cookie-store/#dictdef-cookielistitem CookieListItem}
  * as specified by W3C.
  */
-interface CookieListItem extends Pick<CookieSerializeOptions, "domain" | "path" | "sameSite" | "secure"> {
-    /** A string with the name of a cookie. */
-    name: string;
-    /** A string containing the value of the cookie. */
-    value: string;
-    /** A number of milliseconds or Date interface containing the expires of the cookie. */
-    expires?: CookieSerializeOptions["expires"] | number;
+interface CookieListItem extends Pick<SetCookie, "domain" | "path" | "sameSite" | "secure"> {
+  /** A string with the name of a cookie. */
+  name: string;
+  /** A string containing the value of the cookie. */
+  value: string;
+  /** A number of milliseconds or Date interface containing the expires of the cookie. */
+  expires?: SetCookie["expires"] | number;
 }
 /**
  * Superset of {@link CookieListItem} extending it with
  * the `httpOnly`, `maxAge` and `priority` properties.
  */
-type ResponseCookie = CookieListItem & Pick<CookieSerializeOptions, "httpOnly" | "maxAge" | "priority">;
+type ResponseCookie = CookieListItem & Pick<SetCookie, "httpOnly" | "priority"> & {
+  maxAge?: number | undefined;
+};
 /**
- * The high-level type definition of the .get() and .set() methods
- * of { cookies() } from "next/headers"
+ * What iron-session needs from a cookie store. This is deliberately the shape
+ * of `await cookies()` from `next/headers`, so it can be passed in directly.
+ *
+ * `getAll` is optional: it is only used to find cookie chunks, and stores that
+ * cannot enumerate are probed by name instead.
  */
 interface CookieStore {
-    get: (name: string) => {
-        name: string;
-        value: string;
-    } | undefined;
-    set: {
-        (name: string, value: string, cookie?: Partial<ResponseCookie>): void;
-        (options: ResponseCookie): void;
-    };
+  get: (name: string) => {
+    name: string;
+    value: string;
+  } | undefined;
+  getAll?: () => {
+    name: string;
+    value: string;
+  }[];
+  /**
+   * One signature with a required third argument, returning `unknown`.
+   *
+   * Every part of that matters for `getIronSession(await cookies(), ...)` to
+   * typecheck against Next.js, which is what #840 was about:
+   *
+   * - not an overload pair. Next declares a single signature over a tuple
+   *   union, and a single signature is not assignable to an overload pair.
+   * - the third argument is required, not optional. Next's tuple element is
+   *   `cookie?: Partial<ResponseCookie>`, and under
+   *   `exactOptionalPropertyTypes` our optional parameter widened to
+   *   `Partial<ResponseCookie> | undefined`, which their tuple rejects. We
+   *   always pass cookie options anyway.
+   * - `unknown` return. Next returns the cookie store itself, not void.
+   */
+  set: (name: string, value: string, cookie: Partial<ResponseCookie>) => unknown;
 }
 /**
- * Set-Cookie Attributes do not include `encode`. We omit this from our `cookieOptions` type.
+ * Set-Cookie attributes. `name` and `value` are owned by iron-session
+ * (`cookieName` and the seal), so they are not configurable here.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie
  * @see https://developer.chrome.com/docs/devtools/application/cookies/
  */
-type CookieOptions = Omit<CookieSerializeOptions, "encode">;
+type CookieOptions = Omit<SetCookie, "name" | "value" | "maxAge"> & {
+  /**
+   * Explicitly allows `undefined` so that `cookieOptions: { maxAge: undefined }`
+   * keeps working under `exactOptionalPropertyTypes`. That is the documented way
+   * to ask for a "session cookie" that the browser drops when it closes.
+   */
+  maxAge?: number | undefined;
+};
+/**
+ * Why an existing cookie could not be read. Every reason results in a fresh,
+ * empty session: a session library cannot tell a tampered cookie from a
+ * badly rotated password, so the only safe outcome is to start over.
+ * Use `onUnsealError` to observe these, they are otherwise invisible.
+ */
+type UnsealErrorReason =
+/** The seal is past its expiration. Normal, this is how sessions end. */
+"expired" |
+/** Integrity check failed, or the value is not a seal at all. Possible tampering. */
+"invalid" |
+/** The seal references a password id that is not in the password map. Usually a rotation mistake. */
+"unknown-password";
 interface SessionOptions {
-    /**
-     * The cookie name that will be used inside the browser. Make sure it's unique
-     * given your application.
-     *
-     * @example 'vercel-session'
-     */
-    cookieName: string;
-    /**
-     * The password(s) that will be used to encrypt the cookie. Can either be a string
-     * or an object.
-     *
-     * When you provide multiple passwords then all of them will be used to decrypt
-     * the cookie. But only the most recent (`= highest key`, `2` in the example)
-     * password will be used to encrypt the cookie. This allows password rotation.
-     *
-     * @example { 1: 'password-1', 2: 'password-2' }
-     */
-    password: Password;
-    /**
-     * The time (in seconds) that the session will be valid for. Also sets the
-     * `max-age` attribute of the cookie automatically (`= ttl - 60s`, so that the
-     * cookie always expire before the session).
-     *
-     * `ttl = 0` means no expiration.
-     *
-     * @default 1209600
-     */
-    ttl?: number;
-    /**
-     * The options that will be passed to the cookie library.
-     *
-     * If you want to use "session cookies" (cookies that are deleted when the browser
-     * is closed) then you need to pass `cookieOptions: { maxAge: undefined }`
-     *
-     * @see https://github.com/jshttp/cookie#options-1
-     */
-    cookieOptions?: CookieOptions;
+  /**
+   * The cookie name that will be used inside the browser. Make sure it's unique
+   * given your application.
+   *
+   * @example 'vercel-session'
+   */
+  cookieName: string;
+  /**
+   * The password(s) that will be used to encrypt the cookie. Can either be a string
+   * or an object.
+   *
+   * When you provide multiple passwords then all of them will be used to decrypt
+   * the cookie. But only the most recent (`= highest key`, `2` in the example)
+   * password will be used to encrypt the cookie. This allows password rotation.
+   *
+   * @example { 1: 'password-1', 2: 'password-2' }
+   */
+  password: Password;
+  /**
+   * The time (in seconds) that the session will be valid for. Also sets the
+   * `max-age` attribute of the cookie automatically (`= ttl - 60s`, so that the
+   * cookie always expire before the session).
+   *
+   * `ttl = 0` means no expiration. Do not use it for authentication: the seal
+   * is then accepted forever and there is no way to revoke it.
+   *
+   * @default 1209600
+   */
+  ttl?: number;
+  /**
+   * The options that will be passed to the cookie library.
+   *
+   * If you want to use "session cookies" (cookies that are deleted when the browser
+   * is closed) then you need to pass `cookieOptions: { maxAge: undefined }`
+   *
+   * @see https://github.com/jshttp/cookie#options-1
+   */
+  cookieOptions?: CookieOptions;
+  /**
+   * Called when an existing cookie could not be read, right before the session
+   * is reset to an empty object.
+   *
+   * A stateless session library cannot tell a tampered cookie from a badly
+   * rotated password, so it always starts a new session rather than throwing.
+   * That is the safe default, but it means genuine problems are invisible:
+   * a `"unknown-password"` burst usually means a broken password rotation, and
+   * an `"invalid"` burst can mean someone is probing your cookies. Log them.
+   *
+   * This hook must not throw. It is not a place to deny access: the session is
+   * empty either way.
+   *
+   * @example
+   * onUnsealError: (reason, error) => {
+   *   if (reason !== "expired") logger.warn({ reason, error }, "session cookie rejected");
+   * }
+   */
+  onUnsealError?: (reason: UnsealErrorReason, error: unknown) => void;
+  /**
+   * Split a session that does not fit in one cookie across several cookies,
+   * named `<cookieName>.0`, `<cookieName>.1` and so on.
+   *
+   * Off by default, and reading works either way: turning this on or off does
+   * not sign anyone out.
+   *
+   * Read the size limits before reaching for this. A browser caps one cookie at
+   * 4096 bytes, but the real constraint is the request side: every cookie is
+   * sent on every request, and proxies cap the whole `Cookie` header well below
+   * what four chunks can produce. nginx allows 8 KB by default, and a CDN or
+   * load balancer in front of it may allow less. Going over that returns 400 or
+   * 431 at the edge, before your app runs, which is much harder to debug than
+   * an error from us. iron-session refuses more than {@link MAX_CHUNKS} chunks
+   * for that reason.
+   *
+   * Chunking is an escape hatch for a session slightly over the limit. If you
+   * need a lot of room, store an id in the session and keep the data in your
+   * database.
+   *
+   * @default false
+   */
+  chunk?: boolean;
 }
-type IronSession<T> = T & {
-    /**
-     * Encrypts the session data and sets the cookie.
-     */
-    readonly save: () => Promise<void>;
-    /**
-     * Destroys the session data and removes the cookie.
-     */
-    readonly destroy: () => void;
-    /**
-     * Update the session configuration. You still need to call save() to send the new cookie.
-     */
-    readonly updateConfig: (newSessionOptions: SessionOptions) => void;
-};
-
-declare const sealData: (data: unknown, { password, ttl, }: {
-    password: string | {
-        [x: string]: string;
-    };
-    ttl?: number;
-}) => Promise<string>;
-declare const unsealData: <T>(seal: string, { password, ttl, }: {
-    password: string | {
-        [x: string]: string;
-    };
-    ttl?: number;
-}) => Promise<T>;
-declare const getIronSession: {
-    <T extends object>(cookies: CookieStore, sessionOptions: SessionOptions): Promise<IronSession<T>>;
-    <T extends object>(req: http.IncomingMessage | Request, res: Response | http.ServerResponse<http.IncomingMessage>, sessionOptions: SessionOptions): Promise<IronSession<T>>;
+/**
+ * A session object: your data, plus `save`, `destroy` and `updateConfig`.
+ *
+ * `T` is wrapped in `Partial` because a session that does not exist yet reads as
+ * an empty object. Declaring `IronSession<{ user: User }>` used to promise that
+ * `session.user` was there, so `session.user.id` typechecked and then threw at
+ * runtime on the first visit, on an expired cookie, and after `destroy()`.
+ */
+type IronSession<T> = Partial<T> & {
+  /**
+   * Encrypts the session data and sets the cookie.
+   */
+  readonly save: () => Promise<void>;
+  /**
+   * Destroys the session data and removes the cookie.
+   */
+  readonly destroy: () => void;
+  /**
+   * Update the session configuration. You still need to call save() to send the new cookie.
+   */
+  readonly updateConfig: (newSessionOptions: SessionOptions) => void;
 };
-
-export { type IronSession, type SessionOptions, getIronSession, sealData, unsealData };
+declare function sealData(data: unknown, { password, ttl }: {
+  password: Password;
+  ttl?: number;
+}): Promise<string>;
+declare function unsealData<T>(seal: string, { password, ttl, onUnsealError }: {
+  password: Password;
+  ttl?: number;
+  onUnsealError?: (reason: UnsealErrorReason, error: unknown) => void;
+}): Promise<T>;
+/**
+ * The one thing iron-session needs from a runtime: read a cookie by name, and
+ * write a cookie back. Everything else (Node req/res, web Request/Response,
+ * Next's `cookies()`, Next's proxy) is an adapter that produces one of these.
+ *
+ * There used to be two copies of the read/save/destroy logic, one per calling
+ * convention, and they drifted: the cookie size limit was computed differently
+ * in each, and only one of them checked whether it was still possible to send a
+ * header. Everything now goes through a single implementation.
+ */
+interface CookieJar {
+  read: (name: string) => string | undefined;
+  write: (name: string, value: string, options: CookieOptions) => void;
+  /**
+   * Names of the cookies present on the request, when the runtime can list
+   * them. Used to find cookie chunks.
+   */
+  names?: () => string[];
+  /**
+   * Throws if a cookie can no longer be sent, for runtimes where writing after
+   * a certain point is silently dropped. Losing a session cookie without an
+   * error is much worse than a loud failure.
+   */
+  assertWritable?: () => void;
+}
+/**
+ * Node's `http` server, which is also Express, Connect and Next.js API routes.
+ *
+ * @example
+ * const session = await getIronSession(nodeCookies(req, res), options);
+ */
+declare function nodeCookies(req: IncomingMessage, res: ServerResponse): CookieJar;
+/**
+ * Web-standard `Request` plus anything with appendable headers: a `Response`,
+ * a bare `Headers`, or Next's `NextResponse`.
+ *
+ * @example
+ * const headers = new Headers();
+ * const session = await getIronSession(webCookies(request, headers), options);
+ * return new Response(body, { headers });
+ */
+declare function webCookies(request: Request, response: Response | Headers): CookieJar;
+/**
+ * The parts of `NextRequest`/`NextResponse` we touch, structurally typed so
+ * `next` is not a dependency.
+ *
+ * Request and response cookies are not the same type in Next: request cookies
+ * take `(name, value)` only, because attributes are meaningless on an incoming
+ * cookie, while response cookies take `(name, value, options)`. Declaring one
+ * shared interface for both is what made `NextRequest` fail to assign.
+ */
+interface NextRequestCookies {
+  get: (name: string) => {
+    name: string;
+    value: string;
+  } | undefined;
+  getAll?: () => {
+    name: string;
+    value: string;
+  }[];
+  set: (name: string, value: string) => unknown;
+}
+interface NextResponseCookies {
+  set: (name: string, value: string, options: Partial<ResponseCookie>) => unknown;
+}
+/**
+ * Next.js `proxy.ts` (called `middleware.ts` before Next 16).
+ *
+ * Writing a raw `set-cookie` header here does not work the way you would
+ * expect: Next only merges a cookie into the current render when it goes
+ * through `response.cookies.set()`, so `session.save()` in middleware appeared
+ * to succeed and then vanished. Writing to `request.cookies` as well makes the
+ * new value visible to code that reads the session later in the same request,
+ * which is what makes rotation work.
+ *
+ * @example
+ * export async function proxy(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   const session = await getIronSession(nextProxyCookies(request, response), options);
+ *   session.lastSeen = Date.now();
+ *   await session.save();
+ *   return response;
+ * }
+ */
+declare function nextProxyCookies(request: {
+  cookies: NextRequestCookies;
+}, response: {
+  cookies: NextResponseCookies;
+}): CookieJar;
+declare function getIronSession<T extends object>(cookies: CookieStore | CookieJar, sessionOptions: SessionOptions): Promise<IronSession<T>>;
+declare function getIronSession<T extends object>(req: RequestType, res: ResponseType, sessionOptions: SessionOptions): Promise<IronSession<T>>;
+//#endregion
+export { type CookieJar, type CookieStore, type IronSession, type SessionOptions, type UnsealErrorReason, getIronSession, nextProxyCookies, nodeCookies, sealData, unsealData, webCookies };
+//# sourceMappingURL=index.d.ts.map