iron-session 7.0.6 → 8.0.0-beta.0

package/README.md

@@ -1,763 +1,495 @@
-# iron-session [![GitHub license](https://img.shields.io/github/license/vvo/iron-session?style=flat)](https://github.com/vvo/iron-session/blob/master/LICENSE) [![Tests](https://github.com/vvo/iron-session/workflows/Tests/badge.svg)](https://github.com/vvo/iron-session/actions) [![npm](https://img.shields.io/npm/v/iron-session)](https://www.npmjs.com/package/iron-session) [![Downloads](https://img.shields.io/npm/dm/next-iron-session.svg)](http://npm-stat.com/charts.html?package=iron-session)
+# iron-session
 
-<p align="center"><b>⭐️ Featured in the <a href="https://nextjs.org/docs/authentication">Next.js documentation</a></b></p>
+A runtime-agnostic stateless session utility. Works with Next.js, Node.js, Deno,
+Bun, and more.
 
-_🛠 Node.js stateless session utility using signed and encrypted cookies to store data. Works with Next.js, Express, NestJs, Fastify, and any Node.js HTTP framework._
+The session data is stored in signed and encrypted cookies ("seals") which can
+only be decoded by your server. There are no session ids, making sessions
+"stateless" from the server point of view. This strategy of storing session data
+is the same technique used by frameworks like
+[Ruby On Rails](https://guides.rubyonrails.org/security.html#session-storage).
 
-The session data is stored in encrypted cookies ("seals"). And only your server can decode the session data. There are no session ids, making iron sessions "stateless" from the server point of view.
+## Table of Contents
 
-This strategy of storing session data is the same technique used by **frameworks like [Ruby On Rails](https://guides.rubyonrails.org/security.html#session-storage)** (their default strategy).
-
-The underlying cryptography library is [iron](https://hapi.dev/module/iron) which was [created by the lead developer of OAuth 2.0](https://hueniversedotcom.wordpress.com/2015/09/19/auth-to-see-the-wizard-or-i-wrote-an-oauth-replacement/).
-
-<p align="center"><b>Online demo: <a href="https://iron-session-example.vercel.app/">https://iron-session-example.vercel.app</a> 👀</b></p>
-
----
-
-_Table of contents:_
+<!-- - [Features](#features) -->
 
 - [Installation](#installation)
-- [Usage (Next.js)](#usage-nextjs)
-- [Advanced usage](#advanced-usage)
-  - [Coding best practices](#coding-best-practices)
-  - [Session wrappers](#session-wrappers)
-  - [Typing session data with TypeScript](#typing-session-data-with-typescript)
-  - [Express](#express)
-  - [Handle password rotation/update the password](#handle-password-rotationupdate-the-password)
-  - [Magic links](#magic-links)
-  - [Impersonation, login as someone else](#impersonation-login-as-someone-else)
-  - [Session cookies](#session-cookies)
-  - [Firebase usage](#firebase-usage)
+- [Usage](#usage)
+- [Options Definitions](#options-definitions)
 - [API](#api)
-  - [ironOptions](#ironoptions)
-  - [Next.js: withIronSessionApiRoute(handler, ironOptions | (req: NextApiRequest, res: NextApiResponse) => IronOptions | Promise\<IronOptions\>)](#nextjs-withironsessionapiroutehandler-ironoptions--req-nextapirequest-res-nextapiresponse--ironoptions--promiseironoptions)
-  - [Next.js: withIronSessionSsr(handler, ironOptions | (req: IncomingMessage, res: ServerResponse) => IronOptions | Promise\<IronOptions\>)](#nextjs-withironsessionssrhandler-ironoptions--req-incomingmessage-res-serverresponse--ironoptions--promiseironoptions)
-  - [Express: ironSession(ironOptions)](#express-ironsessionironoptions)
-  - [session.save()](#sessionsave)
-  - [session.destroy()](#sessiondestroy)
+  - [Iron Session Object](#iron-session-object)
+  - [Functions](#iron-session-functions)
+  - [Options](#iron-session-options)
+  - [Example](#nextjs-example)
 - [FAQ](#faq)
-  - [Why use pure cookies for sessions?](#why-use-pure-cookies-for-sessions)
-  - [What are the drawbacks?](#what-are-the-drawbacks)
-  - [How is this different from JWT?](#how-is-this-different-from-jwt)
-- [Project status](#project-status)
+  <!-- - [Contributing](#contributing) -->
+  <!-- - [License](#license) -->
 - [Credits](#credits)
-- [References](#references)
-- [Contributors](#contributors)
+- [Good Reads](#good-reads)
 
 ## Installation
 
-```bash
+```sh
 npm add iron-session
 ```
 
-## Usage (Next.js)
-
-You can find full featured examples (Next.js, Express) in the [examples folder](examples).
-
-The password is a private key you must pass at runtime and builtime (for getServerSideProps), it has to be at least 32 characters long. You can use https://1password.com/password-generator/ to generate strong passwords.
-
-Session duration is 14 days by default, check the API docs for more info.
-
-⚠️ Always store passwords in encrypted environment variables on your platform. Vercel does this automatically.
-
-**Login API Route:**
-
-```ts
-// pages/api/login.ts
-
-import { withIronSessionApiRoute } from "iron-session/next";
-
-export default withIronSessionApiRoute(
-  async function loginRoute(req, res) {
-    // get user from database then:
-    req.session.user = {
-      id: 230,
-      admin: true,
-    };
-    await req.session.save();
-    res.send({ ok: true });
-  },
-  {
-    cookieName: "myapp_cookiename",
-    password: "complex_password_at_least_32_characters_long",
-    // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-    cookieOptions: {
-      secure: process.env.NODE_ENV === "production",
-    },
-  },
-);
-```
-
-**User API Route:**
-
-```ts
-// pages/api/user.ts
+Change the package manager to whatever you use, of course. On Deno, you can use
+[esm.sh](https://esm.sh/):
 
-import { withIronSessionApiRoute } from "iron-session/next";
-
-export default withIronSessionApiRoute(
-  function userRoute(req, res) {
-    res.send({ user: req.session.user });
-  },
-  {
-    cookieName: "myapp_cookiename",
-    password: "complex_password_at_least_32_characters_long",
-    // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-    cookieOptions: {
-      secure: process.env.NODE_ENV === "production",
-    },
-  },
-);
+```js
+import { getIronSession } from 'https://esm.sh/iron-session@latest'
 ```
 
-**Logout Route:**
+## Usage
 
-```ts
-// pages/api/logout.ts
+Refer to the [examples](examples).
 
-import { withIronSessionApiRoute } from "iron-session/next";
+1. Define your session options
+1. Initialize your session with:
+    - sessionOptions and the respective parameters
+    - the type definition of your session data
+1. Set the session data variables
+1. Set the data to or read the data from the browser cookie storage
+    - session.save(): Set the session variables as an encrypted string to the browser cookie storage
+    - session.destroy(): Set cookie value in the browser cookie storage as an empty value to clear the cookie data
+    - Read the session variables by decrypting the encrypted string from the cookie browser storage
 
-export default withIronSessionApiRoute(
-  function logoutRoute(req, res, session) {
-    req.session.destroy();
-    res.send({ ok: true });
-  },
-  {
-    cookieName: "myapp_cookiename",
-    password: "complex_password_at_least_32_characters_long",
-    // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-    cookieOptions: {
-      secure: process.env.NODE_ENV === "production",
-    },
-  },
-);
-```
+## Options Definitions
 
-**getServerSideProps:**
-
-```ts
-// pages/admin.tsx
-
-import { withIronSessionSsr } from "iron-session/next";
-
-export const getServerSideProps = withIronSessionSsr(
-  async function getServerSideProps({ req }) {
-    const user = req.session.user;
+Only two options are required: `password` and `cookieName`. Everything else is automatically computed and usually doesn't need to be changed.
 
-    if (user.admin !== true) {
-      return {
-        notFound: true,
-      };
-    }
+- `password`, **required**: Private key used to encrypt the cookie. It has to be at least 32 characters long. Use <https://1password.com/password-generator/> to generate strong passwords. `password` can be either a `string` or an `array` of objects like this: `[{id: 2, password: "..."}, {id: 1, password: "..."}]` to allow for password rotation.
+- `cookieName`, **required**: Name of the cookie to be stored
+- `ttl`, _optional_: In seconds. Default to the equivalent of 14 days. You can set this to `0` and iron-session will compute the maximum allowed value by cookies (~70 years).
+- `cookieOptions`, _optional_: Any option available from [jshttp/cookie#serialize](https://github.com/jshttp/cookie#cookieserializename-value-options) except for `encode` which is not a Set-Cookie Attribute. See [Mozilla Set-Cookie Attributes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes) and [Chrome Cookie Fields](https://developer.chrome.com/docs/devtools/application/cookies/#fields). Default to:
 
-    return {
-      props: {
-        user: req.session.user,
-      },
-    };
-  },
-  {
-    cookieName: "myapp_cookiename",
-    password: "complex_password_at_least_32_characters_long",
-    // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-    cookieOptions: {
-      secure: process.env.NODE_ENV === "production",
-    },
-  },
-);
+```js
+{
+  httpOnly: true,
+  secure: true, // true when using https, false otherwise
+  sameSite: "lax", // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite#lax
+  // The next line makes sure browser will expire cookies before seals are considered expired by the server. It also allows for clock difference of 60 seconds maximum between servers and clients.
+  maxAge: (ttl === 0 ? 2147483647 : ttl) - 60,
+  path: "/",
+  // other options:
+  // domain, if you want the cookie to be valid for the whole domain and subdomains, use domain: example.com
+  // expires, there should be no need to use this option, maxAge takes precedence
+  // ...
+}
 ```
 
-Note: We encourage you to create a `withSession` utility so you do not have to repeat the password and cookie name in every route. You can see how to do that [in the example](./examples/next.js-typescript/lib/session.ts).
+The final type definition for `CookieOptions` ends up to be
 
-## Advanced usage
+`'domain' | 'path' | 'secure' | 'sameSite' | 'name' | 'value' | 'expires' | 'httpOnly' | 'maxAge' | 'priority'`
 
-### Coding best practices
+### Type Definitions from iron-session/dist/index.node.d.cts
 
-Here's an example Login API route that is easier to read because of less nesting:
+#### IronSessionOptions
 
 ```ts
-// pages/api/login.ts
-
-import { withIronSessionApiRoute } from "iron-session/next";
-import { ironOptions } from "lib/config";
-
-export default withIronSessionApiRoute(loginRoute, ironOptions);
-
-async function loginRoute(req, res) {
-  // get user from database then:
-  req.session.user = {
-    id: 230,
-    admin: true,
-  };
-  await req.session.save();
-  res.send({ ok: true });
+interface IronSessionOptions {
+    /**
+     * 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;
 }
 ```
 
-```ts
-// lib/config.ts
-
-export const ironOptions = {
-  cookieName: "myapp_cookiename",
-  password: "complex_password_at_least_32_characters_long",
-  // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-  cookieOptions: {
-    secure: process.env.NODE_ENV === "production",
-  },
-};
-```
-
-### Session wrappers
-
-If you do not want to pass down the password and cookie name in every API route file or page then you can create wrappers like this:
-
-**JavaScript:**
-
-```js
-// lib/withSession.js
-
-import { withIronSessionApiRoute, withIronSessionSsr } from "iron-session/next";
-
-const sessionOptions = {
-  password: "complex_password_at_least_32_characters_long",
-  cookieName: "myapp_cookiename",
-  // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-  cookieOptions: {
-    secure: process.env.NODE_ENV === "production",
-  },
-};
-
-export function withSessionRoute(handler) {
-  return withIronSessionApiRoute(handler, sessionOptions);
-}
+##### CookieOptions
 
-export function withSessionSsr(handler) {
-  return withIronSessionSsr(handler, sessionOptions);
-}
+```ts
+/**
+ * Set-Cookie Attributes do not include `encode`. We omit this from our `cookieOptions` type.
+ *
+ * @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'>
 ```
 
-**TypeScript:**
+##### CookieSerializeOptions
 
 ```ts
-// lib/withSession.ts
-
-import { withIronSessionApiRoute, withIronSessionSsr } from "iron-session/next";
-import {
-  GetServerSidePropsContext,
-  GetServerSidePropsResult,
-  NextApiHandler,
-} from "next";
-
-const sessionOptions = {
-  password: "complex_password_at_least_32_characters_long",
-  cookieName: "myapp_cookiename",
-  // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-  cookieOptions: {
-    secure: process.env.NODE_ENV === "production",
-  },
-};
-
-export function withSessionRoute(handler: NextApiHandler) {
-  return withIronSessionApiRoute(handler, sessionOptions);
+interface CookieSerializeOptions {
+    /**
+     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.3|Domain Set-Cookie attribute}. By default, no
+     * domain is set, and most clients will consider the cookie to apply to only
+     * the current domain.
+     */
+    domain?: string | undefined;
+
+    /**
+     * Specifies a function that will be used to encode a cookie's value. Since
+     * value of a cookie has a limited character set (and must be a simple
+     * string), this function can be used to encode a value into a string suited
+     * for a cookie's value.
+     *
+     * The default function is the global `encodeURIComponent`, which will
+     * encode a JavaScript string into UTF-8 byte sequences and then URL-encode
+     * any that fall outside of the cookie range.
+     */
+    encode?(value: string): string;
+
+    /**
+     * Specifies the `Date` object to be the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.1|`Expires` `Set-Cookie` attribute}. By default,
+     * no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete
+     * it on a condition like exiting a web browser application.
+     *
+     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+     * possible not all clients by obey this, so if both are set, they should
+     * point to the same date and time.
+     */
+    expires?: Date | undefined;
+    /**
+     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.6|`HttpOnly` `Set-Cookie` attribute}.
+     * When truthy, the `HttpOnly` attribute is set, otherwise it is not. By
+     * default, the `HttpOnly` attribute is not set.
+     *
+     * *Note* be careful when setting this to true, as compliant clients will
+     * not allow client-side JavaScript to see the cookie in `document.cookie`.
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Specifies the number (in seconds) to be the value for the `Max-Age`
+     * `Set-Cookie` attribute. The given number will be converted to an integer
+     * by rounding down. By default, no maximum age is set.
+     *
+     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+     * possible not all clients by obey this, so if both are set, they should
+     * point to the same date and time.
+     */
+    maxAge?: number | undefined;
+    /**
+     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.4|`Path` `Set-Cookie` attribute}.
+     * By default, the path is considered the "default path".
+     */
+    path?: string | undefined;
+    /**
+     * Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].
+     *
+     * - `'low'` will set the `Priority` attribute to `Low`.
+     * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+     * - `'high'` will set the `Priority` attribute to `High`.
+     *
+     * More information about the different priority levels can be found in
+     * [the specification][rfc-west-cookie-priority-00-4.1].
+     *
+     * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means many clients may ignore this attribute until they understand it.
+     */
+    priority?: 'low' | 'medium' | 'high' | undefined;
+    /**
+     * Specifies the boolean or string to be the value for the {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|`SameSite` `Set-Cookie` attribute}.
+     *
+     * - `true` will set the `SameSite` attribute to `Strict` for strict same
+     * site enforcement.
+     * - `false` will not set the `SameSite` attribute.
+     * - `'lax'` will set the `SameSite` attribute to Lax for lax same site
+     * enforcement.
+     * - `'strict'` will set the `SameSite` attribute to Strict for strict same
+     * site enforcement.
+     *  - `'none'` will set the SameSite attribute to None for an explicit
+     *  cross-site cookie.
+     *
+     * More information about the different enforcement levels can be found in {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|the specification}.
+     *
+     * *note* This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
+     */
+    sameSite?: true | false | 'lax' | 'strict' | 'none' | undefined;
+    /**
+     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.5|`Secure` `Set-Cookie` attribute}. When truthy, the
+     * `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
+     *
+     * *Note* be careful when setting this to `true`, as compliant clients will
+     * not send the cookie back to the server in the future if the browser does
+     * not have an HTTPS connection.
+     */
+    secure?: boolean | undefined;
 }
 
-// Theses types are compatible with InferGetStaticPropsType https://nextjs.org/docs/basic-features/data-fetching#typescript-use-getstaticprops
-export function withSessionSsr<
-  P extends { [key: string]: unknown } = { [key: string]: unknown },
->(
-  handler: (
-    context: GetServerSidePropsContext,
-  ) => GetServerSidePropsResult<P> | Promise<GetServerSidePropsResult<P>>,
-) {
-  return withIronSessionSsr(handler, sessionOptions);
-}
 ```
 
-**Usage in API Routes:**
-
-```ts
-// pages/api/login.ts
-
-import { withSessionRoute } from "lib/withSession";
+## API
 
-export default withSessionRoute(loginRoute);
+## Iron Session Object
 
-async function loginRoute(req, res) {
-  // get user from database then:
-  req.session.user = {
-    id: 230,
-    admin: true,
-  };
-  await req.session.save();
-  res.send("Logged in");
-}
-```
-
-**Usage in getServerSideProps:**
+### getIronSession(req: Request | IncomingMessage, res: Response | ServerResponse<IncomingMessage>, userSessionOptions: IronSessionOptions): Promise<IronSession<T>>
 
 ```ts
-// pages/admin.tsx
-
-import { withSessionSsr } from "lib/withSession";
-
-export const getServerSideProps = withSessionSsr(
-  async function getServerSideProps({ req }) {
-    const user = req.session.user;
-
-    if (user.admin !== true) {
-      return {
-        notFound: true,
-      };
-    }
-
-    return {
-      props: {
-        user: req.session.user,
-      },
-    };
-  },
-);
+const session = getIronSession<IronSessionData>(req, res, sessionOptions)
 ```
 
-### Typing session data with TypeScript
-
-`req.session` is automatically populated with the right types so .save() and .destroy() can be called on it.
+The API Route Handler that uses `getIronSession` and returns the Response needs to be called from a client-side environment (ie. a 'use client' file).
 
-But you might want to go further and type your session data also. To do so, use [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation):
+### getServerActionIronSession(userSessionOptions: IronSessionOptions, cookieHandler: ICookieHandler): Promise<IronSession<T>>
 
 ```ts
-declare module "iron-session" {
-  interface IronSessionData {
-    user?: {
-      id: number;
-      admin?: boolean;
-    };
-  }
-}
+const session = getServerActionIronSession<IronSessionData>(sessionOptions, cookies())
 ```
 
-You can put this code anywhere in your project, as long as it is in a file that will be required at some point. For example it could be inside your `lib/withSession.ts` wrapper or inside an [`additional.d.ts`](https://nextjs.org/docs/basic-features/typescript) if you're using Next.js.
+The `getServerActionIronSession` implementation uses the `cookies()` function from next/headers to set the cookies so that Iron Session can be used in NextJS Server Actions and React Server Components in a server-side environment (ie. a 'use server' file).
 
-We've taken this technique from [express-session types](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/express-session). If you have any comment on
+## Iron Session Functions
 
-### Express
+### session.save(saveOptions?: OverridableOptions)
 
-See [examples/express](examples/express) for an example of how to use this with Express.
+Saves the session and sets the cookie header to be sent once the response is sent.
 
-### Handle password rotation/update the password
+```ts
+await session.save()
+```
 
-When you want to:
+### session.destroy(destroyOptions?: OverridableOptions)
 
-- rotate passwords for better security every two (or more, or less) weeks
-- change the password you previously used because it leaked somewhere (😱)
+Empties the session object and sets the cookie header to be sent once the response is sent. The browser will then set the cookie value as an empty value.
 
-Then you can use multiple passwords:
+```ts
+await session.destroy()
+```
 
-**Week 1**:
+Upon calling either `session.save()` or `session.destroy()` the session values are saved to the browser cookie storage.
 
-```js
-withIronSessionApiRoute(handler, {
-  password: {
-    1: "complex_password_at_least_32_characters_long",
-  },
-});
-```
+## Iron Session Options
 
-**Week 2**:
+### Default Options
 
-```js
-withIronSessionApiRoute(handler, {
-  password: {
-    2: "another_password_at_least_32_characters_long",
-    1: "complex_password_at_least_32_characters_long",
-  },
-});
+```ts
+const defaultOptions: Required<OverridableOptions> = {
+  ttl: fourteenDaysInSeconds,
+  cookieOptions: { httpOnly: true, secure: true, sameSite: 'lax', path: '/' },
+}
 ```
 
-**Notes:**
-
-- The password used to encrypt session data (to `seal`) is always the highest number found in the map (2 in the example).
-- The passwords used to decrypt session data are all passwords in the map (this is how rotation works).
-- Even if you do not provide a list at first, you can always move to multiple passwords afterwards. The first password you've used has a default id of 1.
+### User Session Options
 
-### Magic links
+You may apply options during the Iron Session object initialization. These options will superseded and override any options set in Default Options. For example: refer to `cookieOptions` in `lib/session.ts` in the below [NextJS Example](#nextjs-example).
 
-Because of the stateless nature of `iron-session`, it's very easy to implement patterns like magic links. For example, you might want to send an email to the user with a link to a page where they will be automatically logged in. Or you might want to send a Slack message to someone with a link to your application where they will be automatically logged in.
+### Override Options
 
-Here's how to implement that:
+You may apply options during the `.save()` or `.destroy()` function calls.  These options will superseded and override any options set in Default Options and User Session Options.
 
-**Send an email with a magic link to the user**:
+For example:
 
 ```ts
-// pages/api/sendEmail.ts
-
-import { sealData } from "iron-session";
-
-export default async function sendEmailRoute(req, res) {
-  const user = getUserFromDatabase(req.query.userId);
-
-  const seal = await sealData(
-    {
-      userId: user.id,
-    },
-    {
-      password: "complex_password_at_least_32_characters_long",
-    },
-  );
-
-  await sendEmail(
-    user.email,
-    "Magic link",
-    `Hey there ${user.name}, <a href="https://myapp.com/api/magicLogin?seal=${seal}">click here to login</a>.`,
-  );
-
-  res.send({ ok: true });
+type OverridableOptions = {
+    ttl?: number;
+    cookieOptions?: CookieOptions;
 }
 ```
 
-The default `ttl` for such seals is 14 days. To specify a `ttl`, provide it in seconds like so:
-
 ```ts
-const fifteenMinutesInSeconds = 15 * 60;
-
-const seal = await sealData(
-  {
-    userId: user.id,
-  },
-  {
-    password: "complex_password_at_least_32_characters_long",
-    ttl: fifteenMinutesInSeconds,
-  },
-);
+await session.save({ cookieOptions: { priority: 'high'} })
 ```
 
-**Login the user automatically and redirect:**
+## NextJS Example
+
+#### lib/session.ts
 
 ```ts
-// pages/api/magicLogin.ts
+import {
+  IronSessionOptions, getIronSession, IronSessionData, getServerActionIronSession
+} from 'iron-session'
 
-import { unsealData } from "iron-session";
-import { withIronSessionApiRoute } from "iron-session/next";
+import { cookies } from 'next/headers';
 
-export default withIronSessionApiRoute(magicLoginRoute, {
-  cookieName: "myapp_cookiename",
-  password: "complex_password_at_least_32_characters_long",
+export const sessionOptions: IronSessionOptions = {
+  password: 'change-this-this-is-not-a-secure-password',
+  cookieName: 'cookieNameInBrowser',
   cookieOptions: {
-    secure: process.env.NODE_ENV === "production",
+    secure: process.env.NODE_ENV === 'production',
   },
-});
-
-async function magicLoginRoute(req, res) {
-  const { userId } = await unsealData(req.query.seal, {
-    password: "complex_password_at_least_32_characters_long",
-  });
+}
 
-  const user = getUserFromDatabase(userId);
+declare module 'iron-session' {
+  interface IronSessionData {
+    cookieVariable?: string;
+  }
+}
 
-  req.session.user = {
-    id: user.id,
-  };
+const getSession = async (req: Request, res: Response) => {
+  const session = getIronSession<IronSessionData>(req, res, sessionOptions)
+  return session
+}
 
-  await req.session.save();
+const getServerActionSession = async () => {
+  const session = getServerActionIronSession<IronSessionData>(sessionOptions, cookies())
+  return session
+}
 
-  res.redirect(`/dashboard`);
+export {
+  getSession,
+  getServerActionSession
 }
 ```
 
-You might want to include error handling in the API routes. For example checking if `req.session.user` is already defined in login or handling bad seals.
-
-### Impersonation, login as someone else
-
-You may want to impersonate your own users, to check how they see your application. This can be extremely useful. For example you could have a page that list all your users and with links you can click to impersonate them.
+### getIronSession
 
-**Login as someone else:**
+#### src/app/clientActions.ts
 
 ```ts
-// pages/api/impersonate.ts
-
-import { withIronSessionApiRoute } from "iron-session/next";
-
-export default withIronSessionApiRoute(impersonateRoute, {
-  cookieName: "myapp_cookiename",
-  password: "complex_password_at_least_32_characters_long",
-  cookieOptions: {
-    secure: process.env.NODE_ENV === "production",
-  },
-});
-
-async function impersonateRoute(req, res) {
-  if (!req.session.isAdmin) {
-    // let's pretend this route does not exists if user is not an admin
-    return res.status(404).end();
-  }
+'use client'
+
+export const submitCookieToStorageRouteHandler = async (cookie: string) => {
+  await fetch('http://localhost:3000/api/submitIronSessionCookie', {
+    method: 'POST',
+    body: JSON.stringify({
+      cookie,
+    }),
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  })
+}
 
-  req.session.originalUser = req.session.originalUser || req.session.user;
-  req.session.user = {
-    id: req.query.userId,
-  };
-  await req.session.save();
-  res.redirect("/dashboard");
+export const readCookieFromStorageRouteHandler = async (): Promise<string> => {
+  const responseWithCookieFromStorage = await fetch('http://localhost:3000/api/readIronSessionCookie', {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  })
+  const data = await responseWithCookieFromStorage.json();
+  const cookieValue = data?.cookieInStorage || 'No Cookie In Storage'
+  return cookieValue
 }
 ```
 
-**Stop impersonation:**
+#### src/api/submitIronSessionCookie/route.ts
 
 ```ts
-// pages/api/stopImpersonate.ts
-
-import { withIronSessionApiRoute } from "iron-session/next";
-
-export default withIronSessionApiRoute(stopImpersonateRoute, {
-  cookieName: "myapp_cookiename",
-  password: "complex_password_at_least_32_characters_long",
-  cookieOptions: {
-    secure: process.env.NODE_ENV === "production",
-  },
-});
-
-async function stopImpersonateRoute(req, res) {
-  if (!req.session.isAdmin) {
-    // let's pretend this route does not exists if user is not an admin
-    return res.status(404).end();
+import { getSession } from '../../../../lib/session'
+
+export async function POST(request: Request) {
+  try {
+    const requestBody = await request.json()
+    const { cookie }: { cookie: string } = requestBody
+    const response = new Response()
+    const session = await getSession(request, response)
+    session.cookieVariable = cookie
+    await session.save()
+    return response
+  } catch (error: unknown) {
+    console.error((error as Error).message)
+    return new Response(JSON.stringify({ message: (error as Error).message }), { status: 500 })
   }
-
-  req.session.user = req.session.originalUser;
-  delete req.session.originalUser;
-  await req.session.save();
-  res.redirect("/dashboard");
 }
 ```
 
-### Session cookies
-
-If you want cookies to expire when the user closes the browser, pass `maxAge: undefined` in cookie options, this way:
+#### src/api/readIronSessionCookie/route.ts
 
 ```ts
-// pages/api/user.ts
-
-import { withIronSessionApiRoute } from "iron-session/next";
-
-export default withIronSessionApiRoute(
-  function userRoute(req, res) {
-    res.send({ user: req.session.user });
-  },
-  {
-    cookieName: "myapp_cookiename",
-    password: "complex_password_at_least_32_characters_long",
-    cookieOptions: {
-      maxAge: undefined,
-      secure: process.env.NODE_ENV === "production",
-    },
-  },
-);
-```
-
-Beware, modern browsers might not delete cookies at all using this technique because of [session restoring](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#define_the_lifetime_of_a_cookie).
-
-### Firebase usage
-
-This library can be used with Firebase, as long as you set the cookie name to `__session` which seems to be the only valid cookie name there.
-
-## API
-
-### ironOptions
-
-Only two options are required: `password` and `cookieName`. Everything else is automatically computed and usually doesn't need to be changed.
-
-- `password`, **required**: Private key used to encrypt the cookie. It has to be at least 32 characters long. Use https://1password.com/password-generator/ to generate strong passwords. `password` can be either a `string` or an `array` of objects like this: `[{id: 2, password: "..."}, {id: 1, password: "..."}]` to allow for password rotation.
-- `cookieName`, **required**: Name of the cookie to be stored
-- `ttl`, _optional_: In seconds. Default to the equivalent of 14 days. You can set this to `0` and iron-session will compute the maximum allowed value by cookies (~70 years).
-- [`cookieOptions`](https://github.com/jshttp/cookie#cookieserializename-value-options), _optional_: Any option available from [jshttp/cookie#serialize](https://github.com/jshttp/cookie#cookieserializename-value-options). Default to:
-
-```js
-{
-  httpOnly: true,
-  secure: true, // true when using https, false otherwise
-  sameSite: "lax", // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite#lax
-  // The next line makes sure browser will expire cookies before seals are considered expired by the server. It also allows for clock difference of 60 seconds maximum between servers and clients.
-  maxAge: (ttl === 0 ? 2147483647 : ttl) - 60,
-  path: "/",
-  // other options:
-  // domain, if you want the cookie to be valid for the whole domain and subdomains, use domain: example.com
-  // encode, there should be no need to use this option, encoding is done by iron-session already
-  // expires, there should be no need to use this option, maxAge takes precedence
+import { NextResponse } from 'next/server'
+import { getSession } from '../../../../lib/session'
+
+export async function GET(request: Request, response: Response) {
+  try {
+    const session = await getSession(request, response)
+    const cookeValue = session.cookieVariable || 'No Cookie Stored!'
+    return NextResponse.json({ cookieInStorage: cookeValue })
+  } catch (error: unknown) {
+    console.error((error as Error).message)
+    return new Response(JSON.stringify({ message: (error as Error).message }), { status: 500 })
+  }
 }
 ```
 
-### Next.js: withIronSessionApiRoute(handler, ironOptions | (req: NextApiRequest, res: NextApiResponse) => IronOptions | Promise\<IronOptions\>)
+### getServerActionIronSession
 
-Wraps a [Next.js API Route](https://nextjs.org/docs/api-routes/dynamic-api-routes) and adds a `session` object to the request.
+#### src/app/serverActions.ts
 
 ```ts
-import { withIronSessionApiRoute } from "iron-session/next";
+'use server'
 
-export default withIronSessionApiRoute(
-  function userRoute(req, res) {
-    res.send({ user: req.session.user });
-  },
-  {
-    cookieName: "myapp_cookiename",
-    password: "complex_password_at_least_32_characters_long",
-    // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-    cookieOptions: {
-      secure: process.env.NODE_ENV === "production",
-    },
-  },
-);
+import { getServerActionSession } from '../../lib/session'
 
-// You can also pass an async or sync function which takes request and response object and return IronSessionOptions
-export default withIronSessionApiRoute(
-  function userRoute(req, res) {
-    res.send({ user: req.session.user });
-  },
-  (req, res) => {
-    // Infer max cookie from request
-    const maxCookieAge = getMaxCookieAge(req);
-    return {
-      cookieName: "myapp_cookiename",
-      password: "complex_password_at_least_32_characters_long",
-      // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-      cookieOptions: {
-        // setMaxCookie age here.
-        maxCookieAge,
-        secure: process.env.NODE_ENV === "production",
-      },
-    };
-  },
-);
-```
+export const submitCookieToStorageServerAction = async (cookie: string) => {
+  const session = await getServerActionSession()
+  session.cookieVariable = cookie
+  await session.save()
+}
 
-### Next.js: withIronSessionSsr(handler, ironOptions | (req: IncomingMessage, res: ServerResponse) => IronOptions | Promise\<IronOptions\>)
+export const readCookieFromStorageServerAction = async (): Promise<string> => {
+  const session = await getServerActionSession()
+  return session.cookieVariable || 'No Cookie Stored!'
+}
+```
 
-Wraps a [Next.js getServerSideProps](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering) and adds a `session` object to the request of the context.
+#### next.config.js
 
 ```ts
-import { withIronSessionSsr } from "iron-session/next";
-
-export const getServerSideProps = withIronSessionSsr(
-  async function getServerSideProps({ req }) {
-    return {
-      props: {
-        user: req.session.user,
-      },
-    };
-  },
-  {
-    cookieName: "myapp_cookiename",
-    password: "complex_password_at_least_32_characters_long",
-    // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-    cookieOptions: {
-      secure: process.env.NODE_ENV === "production",
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    experimental: {
+      serverActions: true,
     },
-  },
-);
-
-// You can also pass an async or sync function which takes request and response object and return IronSessionOptions
-export const getServerSideProps = withIronSessionSsr(
-  async function getServerSideProps({ req }) {
-    return {
-      props: {
-        user: req.session.user,
-      },
-    };
-  },
-  (req, res) => {
-    return {
-      cookieName: "myapp_cookiename",
-      password: "complex_password_at_least_32_characters_long",
-      // secure: true should be used in production (HTTPS) but can't be used in development (HTTP)
-      cookieOptions: {
-        secure: process.env.NODE_ENV === "production",
-      },
-    };
-  },
-);
-```
-
-### Express: ironSession(ironOptions)
-
-Creates an express middleware that adds a `session` object to the request.
-
-```js
-import { ironSession } from "iron-session/express";
-
-app.use(ironSession(ironOptions));
-```
-
-### session.save()
-
-Saves the session and sets the cookie header to be sent once the response is sent.
+  }
 
-```ts
-await req.session.save();
+module.exports = nextConfig
 ```
 
-### session.destroy()
-
-Empties the session object and sets the cookie header to be sent once the response is sent. The browser will then remove the cookie automatically.
-
-You don't have to call `req.session.save()` after calling `req.session.destroy()`. The session is saved automatically.
-
 ## FAQ
 
-### Why use pure cookies for sessions?
-
-This makes your sessions stateless: you do not have to store session data on your server. You do not need another server or service to store session data. This is particularly useful in serverless architectures where you're trying to reduce your backend dependencies.
-
-### What are the drawbacks?
-
-There are some drawbacks to this approach:
-
-- you cannot invalidate a seal when needed because there's no state stored on the server-side about them. We consider that the way the cookie is stored reduces the possibility for this eventuality to happen. Also, in most applications the first thing you do when receiving an authenticated request is to validate the user and their rights in your database, which defeats the case where someone would try to use a token while their account was deactivated/deleted. Now if someone steals a user token you should have a process in place to mitigate that: deactivate the user and force a re-login with a flag in your database for example.
-- application not supporting cookies won't work, but you can use [iron-store](https://github.com/vvo/iron-store/) to implement something similar. In the future, we could allow `iron-session` to accept [basic auth](https://tools.ietf.org/html/rfc7617) or bearer token methods too. Open an issue if you're interested.
-- on most browsers, you're limited to 4,096 bytes per cookie. To give you an idea, an `iron-session` cookie containing `{user: {id: 100}}` is 265 bytes signed and encrypted: still plenty of available cookie space in here.
-- performance: crypto on the server-side could be slow, if that's the case let me know. Also, cookies are sent to every request to your website, even images, so this could be an issue
+### When should I use getIronSession or getServerActionIronSession?
 
-Now that you know the drawbacks, you can decide if they are an issue for your application or not.
-More information can also be found on the [Ruby On Rails website](https://guides.rubyonrails.org/security.html#session-storage) which uses the same technique.
+Use `getIronSession` when you wish to use Iron Session in a client-side environment with API Route Handlers and use  `getServerActionIronSession` when you wish to use Iron Session in a server-side environment with Server Components.
 
-### How is this different from [JWT](https://jwt.io/)?
+For NextJS projects using App Router with Server Actions enabled in their `next.config.js` file, using `getServerActionIronSession` is preferable for two reasons:
 
-Not so much:
-
-- JWT is a standard, it stores metadata in the JWT token themselves to ensure communication between different systems is flawless.
-- JWT tokens are not encrypted, the payload is visible by customers if they manage to inspect the seal. You would have to use [JWE](https://tools.ietf.org/html/rfc7516) to achieve the same.
-- @hapi/iron mechanism is not a standard, it's a way to sign and encrypt data into seals
-
-Depending on your own needs and preferences, `iron-session` may or may not fit you.
-
-## Project status
-
-✅ Production ready and maintained.
+- allows Iron Session to be called and used from a server-side environment
+- allows for more concise code. Server Actions can be called directly from your components without the need for a manually created API route. You can see the smaller amount of code used for `getServerActionIronSession` compared to `getIronSession` in the example.
 
 ## Credits
 
-Thanks to [Hoang Vo](https://github.com/hoangvvo) for advice and guidance while building this module. Hoang built [next-connect](https://github.com/hoangvvo/next-connect) and [next-session](https://github.com/hoangvvo/next-session).
-
-Thanks to [hapi](https://hapi.dev/) team for creating [iron](https://github.com/hapijs/iron).
-
-## References
-
-- https://owasp.org/www-project-cheat-sheets/cheatsheets/Session_Management_Cheat_Sheet.html#cookies
-- https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#samesite-cookie-attribute
-
-## Contributors
-
-Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
-
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
-<table>
-  <tr>
-    <td align="center"><a href="http://www.afterecon.com/"><img src="https://avatars.githubusercontent.com/u/5559355?v=4?s=100" width="100px;" alt=""/><br /><sub><b>John Vandivier</b></sub></a><br /><a href="https://github.com/vvo/iron-session/commits?author=Vandivier" title="Code">💻</a> <a href="#ideas-Vandivier" title="Ideas, Planning, & Feedback">🤔</a> <a href="#example-Vandivier" title="Examples">💡</a></td>
-    <td align="center"><a href="https://searchableguy.com"><img src="https://avatars.githubusercontent.com/u/73341821?v=4?s=100" width="100px;" alt=""/><br /><sub><b>searchableguy</b></sub></a><br /><a href="https://github.com/vvo/iron-session/commits?author=searchableguy" title="Tests">⚠️</a> <a href="https://github.com/vvo/iron-session/commits?author=searchableguy" title="Documentation">📖</a> <a href="https://github.com/vvo/iron-session/commits?author=searchableguy" title="Code">💻</a></td>
-  </tr>
-</table>
-
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+- [Eran Hammer and hapi.js contributors](https://github.com/hapijs/iron/graphs/contributors)
+  for creating the underlying cryptography library
+  [`@hapi/iron`](https://hapi.dev/module/iron/).
+- [Divyansh Singh](https://github.com/brc-dd) for reimplementing `@hapi/iron` as
+  [`iron-webcrypto`](https://github.com/brc-dd/iron-webcrypto) using standard
+  web APIs.
+- [Hoang Vo](https://github.com/hoangvvo) for advice and guidance while building
+  this module. Hoang built
+  [`next-connect`](https://github.com/hoangvvo/next-connect) and
+  [`next-session`](https://github.com/hoangvvo/next-session).
+- All the
+  [contributors](https://github.com/vvo/iron-session/graphs/contributors) for
+  making this project better.
+
+## Good Reads
+
+- <https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html>
+- <https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html>