iron-session 2.0.0-alpha.14 → 2.0.0-alpha.18

package/README.md

@@ -1,103 +1,346 @@
-# TSDX User Guide
+# 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) [![codecov](https://codecov.io/gh/vvo/iron-session/branch/master/graph/badge.svg)](https://codecov.io/gh/vvo/iron-session) ![npm](https://img.shields.io/npm/v/iron-session) [![Downloads](https://img.shields.io/npm/dm/iron-session.svg)](http://npm-stat.com/charts.html?package=iron-session) [![Github All Contributors](https://img.shields.io/github/all-contributors/vvo/iron-session)](#contributors-)
 
-Congrats! You just saved yourself hours of work by bootstrapping this project with TSDX. Let’s get you oriented with what’s here and how to use it.
+_🛠 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._
 
-> This TSDX setup is meant for developing libraries (not apps!) that can be published to NPM. If you’re looking to build a Node app, you could use `ts-node-dev`, plain `ts-node`, or simple `tsc`.
+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.
 
-> If you’re new to TypeScript, checkout [this handy cheatsheet](https://devhints.io/typescript)
+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)**.
 
-## Commands
+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/).
 
-TSDX scaffolds your new library inside `/src`.
+<p align="center"><b>Online demo at <a href="https://iron-session.now.sh/">https://iron-session.now.sh/</a> 👀</b></p>
 
-To run TSDX, use:
+---
+
+_Table of contents:_
+
+- [Installation](#installation)
+- [Usage (Next.js)](#usage-nextjs)
+- [Advanced usage](#advanced-usage)
+  - [Express](#express)
+  - [Handle password rotation/update the password](#handle-password-rotationupdate-the-password)
+- [API](#api)
+  - [withIronSession(handler, { password, cookieName, [ttl], [cookieOptions] })](#withironsessionhandler--password-cookiename-ttl-cookieoptions-)
+  - [ironSession({ password, cookieName, [ttl], [cookieOptions] })](#ironsession-password-cookiename-ttl-cookieoptions-)
+  - [async applySession(req, res, { password, cookieName, [ttl], [cookieOptions] })](#async-applysessionreq-res--password-cookiename-ttl-cookieoptions-)
+  - [req.session.set(name, value)](#reqsessionsetname-value)
+  - [req.session.get(name)](#reqsessiongetname)
+  - [req.session.unset(name)](#reqsessionunsetname)
+  - [req.session.save() => promise](#reqsessionsave--promise)
+  - [req.session.destroy()](#reqsessiondestroy)
+- [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)
+- [Credits](#credits)
+- [🤓 References](#-references)
+- [Contributors ✨](#contributors-)
+
+## Installation
 
 ```bash
-npm start # or yarn start
+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.
+
+⚠️ Always store passwords in encrypted environment variables on your platform. Vercel does this automatically.
+
+**Login:**
+
+```ts
+// pages/api/login.ts
+
+import { withIronSessionApiRoute } from "iron-session/next";
+
+export default withIronSessionApiRoute(
+  async function handler(req, res) {
+    // get user from database then:
+    req.session.set("user", {
+      id: 230,
+      admin: true,
+    });
+    await req.session.save();
+    res.send("Logged in");
+  },
+  {
+    cookieName: "myapp_cookiename",
+    password: "complex_password_at_least_32_characters_long",
+  },
+);
 ```
 
-This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`.
+**Read user data:**
 
-To do a one-off build, use `npm run build` or `yarn build`.
+```ts
+// pages/api/user.ts
 
-To run tests, use `npm test` or `yarn test`.
+import { withIronSessionApiRoute } from "iron-session/next";
 
-## Configuration
+export default withIronSessionApiRoute(
+  function handler(req, res, session) {
+    const user = req.session.get("user");
+    res.send({ user });
+  },
+  {
+    cookieName: "myapp_cookiename",
+    password: "...",
+  },
+);
+```
+
+**Logout:**
 
-Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly.
+```ts
+// pages/api/logout.ts
 
-### Jest
+import { withIronSessionApiRoute } from "iron-session/next";
+
+export default withIronSessionApiRoute(
+  function handler(req, res, session) {
+    req.session.destroy();
+    res.send("Logged out");
+  },
+  {
+    cookieName: "myapp_cookiename",
+    password: "...",
+  },
+);
+```
 
-Jest tests are set up to run with `npm test` or `yarn test`.
+**getServerSideProps:**
 
-### Bundle Analysis
+```ts
+// pages/admin.tsx
 
-[`size-limit`](https://github.com/ai/size-limit) is set up to calculate the real cost of your library with `npm run size` and visualize the bundle with `npm run analyze`.
+import { withIronSessionSsr } from "iron-session/next";
 
-#### Setup Files
+export const getServerSideProps = withIronSessionSsr(
+  async function getServerSideProps({ req }) {
+    const user = req.session.get("user");
 
-This is the folder structure we set up for you:
+    if (user.admin !== true) {
+      return {
+        notFound: true,
+      };
+    }
 
-```txt
-/src
-  index.tsx       # EDIT THIS
-/test
-  blah.test.tsx   # EDIT THIS
-.gitignore
-package.json
-README.md         # EDIT THIS
-tsconfig.json
+    return {
+      props: {},
+    };
+  },
+  {
+    cookieName: "myapp_cookiename",
+    password: "...",
+  },
+);
 ```
 
-### Rollup
+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).
 
-TSDX uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details.
+## Advanced usage
 
-### TypeScript
+### Express
 
-`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs.
+You can import and use `ironSession` if you want to use `iron-session` in [Express](https://expressjs.com/) and [Connect](https://github.com/senchalabs/connect).
 
-## Continuous Integration
+```js
+import { ironSession } from "iron-session";
+
+const session = ironSession({
+  cookieName: "iron-session/examples/express",
+  password: process.env.SECRET_COOKIE_PASSWORD,
+  // if your localhost is served on http:// then disable the secure flag
+  cookieOptions: {
+    secure: process.env.NODE_ENV === "production",
+  },
+});
+
+router.get("/profile", session, async function (req, res) {
+  // now you can access all of the req.session.* utilities
+  if (req.session.get("user") === undefined) {
+    res.redirect("/restricted");
+    return;
+  }
+
+  res.render("profile", {
+    title: "Profile",
+    userId: req.session.get("user").id,
+  });
+});
+```
+
+A more complete example using Express can be found in the [examples folder](./examples/express).
+
+### Handle password rotation/update the password
 
-### GitHub Actions
+When you want to:
 
-Two actions are added by default:
+- rotate passwords for better security every two (or more, or less) weeks
+- change the password you previously used because it leaked somewhere (😱)
 
-- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
-- `size` which comments cost comparison of your library on every pull request using [`size-limit`](https://github.com/ai/size-limit)
+Then you can use multiple passwords:
 
-## Optimizations
+**Week 1**:
 
-Please see the main `tsdx` [optimizations docs](https://github.com/palmerhq/tsdx#optimizations). In particular, know that you can take advantage of development-only optimizations:
+```js
+export default withIronSession(handler, {
+  password: [
+    {
+      id: 1,
+      password: "complex_password_at_least_32_characters_long",
+    },
+  ],
+});
+```
+
+**Week 2**:
 
 ```js
-// ./types/index.d.ts
-declare var __DEV__: boolean;
+export default withIronSession(handler, {
+  password: [
+    {
+      id: 2,
+      password: "another_password_at_least_32_characters_long",
+    },
+    {
+      id: 1,
+      password: "complex_password_at_least_32_characters_long",
+    },
+  ],
+});
+```
 
-// inside your code...
-if (__DEV__) {
-  console.log('foo');
+Notes:
+
+- `id` is required so that we do not have to try every password in the list when decrypting (the `id` is part of the cookie value).
+- The password used to encrypt session data (to `seal`) is always the first one in the array, so when rotating to put a new password, it must be first in the array list
+- Even if you do not provide an array at first, you can always move to array based passwords afterwards, knowing that your first password (`string`) was given `{id:1}` automatically.
+
+## API
+
+### withIronSession(handler, { password, cookieName, [ttl], [cookieOptions] })
+
+This can be used to wrap Next.js [`getServerSideProps`](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering) or [API Routes](https://nextjs.org/docs/api-routes/introduction) so you can then access all `req.session.*` methods.
+
+- `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 14 days
+- [`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,
+  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 server 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
 }
 ```
 
-You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions.
+### ironSession({ password, cookieName, [ttl], [cookieOptions] })
+
+Connect middleware.
+
+```js
+import { ironSession } from "iron-session";
+
+app.use(ironSession({ ...options }));
+```
+
+### async applySession(req, res, { password, cookieName, [ttl], [cookieOptions] })
+
+Allows you to use this module the way you want as long as you have access to `req` and `res`.
+
+```js
+import { applySession } from "iron-session";
+
+await applySession(req, res, options);
+```
+
+### req.session.set(name, value)
+
+### req.session.get(name)
+
+### req.session.unset(name)
+
+### req.session.save() => promise
+
+### req.session.destroy()
+
+Note: If you use `req.session.destroy()` in an API route, you need to make sure this route will not be cached. To do so, either call this route via a POST request `fetch("/api/logout", { method: "POST" })` or add `cache-control: no-store, max-age=0` to its response.
+
+See https://github.com/vvo/iron-session/issues/274 for more details.
+
+## 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, a `iron-session` cookie containing `{user: {id: 230, admin: true}}` is 358 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
+
+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.
+
+### How is this different from [JWT](https://jwt.io/)?
+
+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.
+
+## Credits
 
-## Module Formats
+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).
 
-CJS, ESModules, and UMD module formats are supported.
+Thanks to [hapi](https://hapi.dev/) team for creating [iron](https://github.com/hapijs/iron).
 
-The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found.
+## 🤓 References
 
-## Named Exports
+- 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
 
-Per Palmer Group guidelines, [always use named exports.](https://github.com/palmerhq/typescript#exports) Code split inside your React app instead of your React library.
+## Contributors ✨
 
-## Including Styles
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
 
-There are many ways to ship styles, including with CSS-in-JS. TSDX has no opinion on this, configure how you like.
+<!-- 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>
+  </tr>
+</table>
 
-For vanilla CSS, you can include it at the root directory and add it to the `files` section in your `package.json`, so that it can be imported separately by your users and run through their bundler's loader.
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
 
-## Publishing to NPM
+<!-- ALL-CONTRIBUTORS-LIST:END -->
 
-We recommend using [np](https://github.com/sindresorhus/np).
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

package/dist/index.cjs

@@ -0,0 +1,181 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __markAsModule = (target) => __defProp(target, "__esModule", { value: true });
+var __export = (target, all) => {
+  __markAsModule(target);
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __reExport = (target, module2, desc) => {
+  if (module2 && typeof module2 === "object" || typeof module2 === "function") {
+    for (let key of __getOwnPropNames(module2))
+      if (!__hasOwnProp.call(target, key) && key !== "default")
+        __defProp(target, key, { get: () => module2[key], enumerable: !(desc = __getOwnPropDesc(module2, key)) || desc.enumerable });
+  }
+  return target;
+};
+var __toModule = (module2) => {
+  return __reExport(__markAsModule(__defProp(module2 != null ? __create(__getProtoOf(module2)) : {}, "default", module2 && module2.__esModule && "default" in module2 ? { get: () => module2.default, enumerable: true } : { value: module2, enumerable: true })), module2);
+};
+
+// src/index.ts
+__export(exports, {
+  getIronSession: () => getIronSession,
+  sealData: () => sealData,
+  unsealData: () => unsealData
+});
+var import_iron = __toModule(require("@hapi/iron"));
+var import_cookie = __toModule(require("cookie"));
+var timestampSkewSec = 60;
+var fourteenDaysInSeconds = 15 * 24 * 3600;
+var currentMajorVersion = 2;
+var versionDelimiter = "#";
+var defaultOptions = {
+  ttl: fourteenDaysInSeconds,
+  cookieOptions: {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/"
+  }
+};
+async function getIronSession(req, res, userSessionOptions) {
+  var _a, _b;
+  if (!req || !res || !userSessionOptions || !userSessionOptions.cookieName || !userSessionOptions.password) {
+    throw new Error(`iron-session: Bad usage. Minimum usage is const session = await getIronSession(req, res, { cookieName: "...", password: "...". Check the usage here: https://github.com/vvo/iron-session`);
+  }
+  const passwordsAsMap = normalizeStringPasswordToMap(userSessionOptions.password);
+  Object.values(normalizeStringPasswordToMap(userSessionOptions.password)).forEach((password) => {
+    if (password.length < 32) {
+      throw new Error(`iron-session: Bad usage. Password must be at least 32 characters long.`);
+    }
+  });
+  const isHttps = req.socket.encrypted === true;
+  if (((_a = userSessionOptions.cookieOptions) == null ? void 0 : _a.secure) === true && isHttps === false) {
+    throw new Error(`iron-session: Can't use secure cookies when not in https. See usage at https://github.com/vvo/iron-session/`);
+  }
+  const options = {
+    ...defaultOptions,
+    ...userSessionOptions,
+    cookieOptions: {
+      ...defaultOptions.cookieOptions,
+      ...userSessionOptions.cookieOptions || {}
+    }
+  };
+  if (((_b = userSessionOptions.cookieOptions) == null ? void 0 : _b.secure) === void 0) {
+    options.cookieOptions.secure = isHttps;
+  }
+  if (options.ttl === 0) {
+    options.ttl = 2147483647;
+  }
+  if (userSessionOptions.cookieOptions && "maxAge" in userSessionOptions.cookieOptions) {
+    if (userSessionOptions.cookieOptions.maxAge === void 0) {
+      options.ttl = 0;
+    } else {
+      options.cookieOptions.maxAge = computeCookieMaxAge(userSessionOptions.cookieOptions.maxAge);
+    }
+  } else {
+    options.cookieOptions.maxAge = computeCookieMaxAge(options.ttl);
+  }
+  const sealFromCookies = (0, import_cookie.parse)(req.headers.cookie || "")[options.cookieName];
+  const session = sealFromCookies === void 0 ? {} : await unsealData(sealFromCookies, passwordsAsMap, options.ttl);
+  Object.defineProperties(session, {
+    save: {
+      value: async function save() {
+        if (res.headersSent === true) {
+          throw new Error(`iron-session: Cannot set session cookie: session.save() was called after headers were sent. Make sure to call it before any res.send() or res.end()`);
+        }
+        const seal = await sealData(session, passwordsAsMap, options.ttl);
+        const cookieValue = (0, import_cookie.serialize)(options.cookieName, seal, options.cookieOptions);
+        if (cookieValue.length > 4096) {
+          throw new Error(`iron-session: Cookie length is too big ${cookieValue.length}, browsers will refuse it. Try to remove some data.`);
+        }
+        addToCookies(cookieValue, res);
+      }
+    },
+    destroy: {
+      value: function destroy() {
+        Object.keys(session).forEach((key) => {
+          delete session[key];
+        });
+        const cookieValue = (0, import_cookie.serialize)(options.cookieName, "", {
+          ...options.cookieOptions,
+          maxAge: 0
+        });
+        addToCookies(cookieValue, res);
+      }
+    }
+  });
+  return session;
+}
+function addToCookies(cookieValue, res) {
+  var _a;
+  let existingSetCookie = (_a = res.getHeader("set-cookie")) != null ? _a : [];
+  if (typeof existingSetCookie === "string") {
+    existingSetCookie = [existingSetCookie];
+  }
+  res.setHeader("set-cookie", [...existingSetCookie, cookieValue]);
+}
+function computeCookieMaxAge(ttl) {
+  return ttl - timestampSkewSec;
+}
+async function unsealData(seal, password, ttl = fourteenDaysInSeconds) {
+  const passwordsAsMap = normalizeStringPasswordToMap(password);
+  const { sealWithoutVersion, tokenVersion } = parseSeal(seal);
+  try {
+    const data = await import_iron.default.unseal(sealWithoutVersion, passwordsAsMap, {
+      ...import_iron.default.defaults,
+      ttl: ttl * 1e3
+    });
+    if (tokenVersion === 2) {
+      return data;
+    }
+    return {
+      ...data.persistent
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.message === "Expired seal" || error.message === "Bad hmac value" || error.message === "Cannot find password: " || error.message === "Incorrect number of sealed components") {
+        return {};
+      }
+    }
+    throw error;
+  }
+}
+function parseSeal(seal) {
+  if (seal[seal.length - 2] === versionDelimiter) {
+    const [sealWithoutVersion, tokenVersionAsString] = seal.split(versionDelimiter);
+    return {
+      sealWithoutVersion,
+      tokenVersion: parseInt(tokenVersionAsString, 10)
+    };
+  }
+  return { sealWithoutVersion: seal, tokenVersion: null };
+}
+async function sealData(data, password, ttl = fourteenDaysInSeconds) {
+  const passwordsAsMap = normalizeStringPasswordToMap(password);
+  const mostRecentPasswordId = Math.max(...Object.keys(passwordsAsMap).map((id) => parseInt(id, 10)));
+  const passwordForSeal = {
+    id: mostRecentPasswordId.toString(),
+    secret: passwordsAsMap[mostRecentPasswordId]
+  };
+  const seal = await import_iron.default.seal(data, passwordForSeal, {
+    ...import_iron.default.defaults,
+    ttl: ttl * 1e3
+  });
+  return `${seal}${versionDelimiter}${currentMajorVersion}`;
+}
+function normalizeStringPasswordToMap(password) {
+  return typeof password === "string" ? { 1: password } : password;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getIronSession,
+  sealData,
+  unsealData
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["import Iron from \"@hapi/iron\";\nimport type { CookieSerializeOptions } from \"cookie\";\nimport { parse as parseCookie, serialize as serializeCookie } from \"cookie\";\nimport type { IncomingMessage, ServerResponse } from \"http\";\nimport type { TLSSocket } from \"tls\";\n\n// default time allowed to check for iron seal validity when ttl passed\n// see https://hapi.dev/family/iron/api/?v=6.0.0#options\nconst timestampSkewSec = 60;\n\ntype passwordsMap = { [id: string]: string };\ntype password = string | passwordsMap;\n\nconst fourteenDaysInSeconds = 15 * 24 * 3600;\n\n// We store a token major version to handle data format changes when any. So that when you upgrade the cookies\n// can be kept alive between upgrades, no need to disconnect everyone.\nconst currentMajorVersion = 2;\nconst versionDelimiter = \"#\";\n\nconst defaultOptions: {\n  ttl: number;\n  cookieOptions: CookieSerializeOptions;\n} = {\n  ttl: fourteenDaysInSeconds,\n  cookieOptions: {\n    httpOnly: true,\n    secure: true,\n    sameSite: \"lax\",\n    path: \"/\",\n  },\n};\n\nexport interface IronSessionOptions {\n  /**\n   * This is the cookie name that will be used inside the browser. You should make sure it's unique given\n   * your application. Example: vercel-session\n   */\n  cookieName: string;\n\n  /**\n   * This is the password(s) that will be used to encrypt the cookie. It can be either a string or an object\n   * like {1: \"password\", 2: password}.\n   *\n   * When you provide multiple passwords then all of them will be used to decrypt the cookie and only the most\n   * recent (= highest key, 2 in this example) password will be used to encrypt the cookie. This allow you\n   * to use password rotation (security)\n   */\n  password: password;\n\n  /**\n   * This is the time in seconds that the session will be valid for. This also set the max-age attribute of\n   * the cookie automatically (minus 60 seconds so that the cookie always expire before the session).\n   */\n  ttl?: number;\n\n  /**\n   * This is the options that will be passed to the cookie library.\n   * You can see all of them here: https://github.com/jshttp/cookie#options-1.\n   *\n   * If you want to use \"session cookies\" (cookies that are deleted when the browser is closed) then you need\n   * to pass cookieOptions: { maxAge: undefined }.\n   */\n  cookieOptions?: CookieSerializeOptions;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface IronSessionData {\n  // If we allow for any keys, then there's no more type check on unknown properties which is not good\n  // If we allow for any keys, the later delete will work but I prefer to disable the check at this stage and\n  // provide good type checking instead\n  // [key: string]: unknown;\n}\n\nexport type IronSession = IronSessionData & {\n  /**\n   * Destroys the session data and removes the cookie.\n   */\n  destroy: () => void;\n\n  /**\n   * Encrypts the session data and sets the cookie.\n   */\n  save: () => Promise<void>;\n};\n\ndeclare module \"http\" {\n  interface IncomingMessage {\n    session: IronSession;\n  }\n}\n\nexport async function getIronSession(\n  req: IncomingMessage,\n  res: ServerResponse,\n  userSessionOptions: IronSessionOptions,\n): Promise<IronSession> {\n  if (\n    !req ||\n    !res ||\n    !userSessionOptions ||\n    !userSessionOptions.cookieName ||\n    !userSessionOptions.password\n  ) {\n    throw new Error(\n      `iron-session: Bad usage. Minimum usage is const session = await getIronSession(req, res, { cookieName: \"...\", password: \"...\". Check the usage here: https://github.com/vvo/iron-session`,\n    );\n  }\n\n  const passwordsAsMap = normalizeStringPasswordToMap(\n    userSessionOptions.password,\n  );\n\n  Object.values(\n    normalizeStringPasswordToMap(userSessionOptions.password),\n  ).forEach((password) => {\n    if (password.length < 32) {\n      throw new Error(\n        `iron-session: Bad usage. Password must be at least 32 characters long.`,\n      );\n    }\n  });\n\n  const isHttps = (req.socket as TLSSocket).encrypted === true;\n\n  if (userSessionOptions.cookieOptions?.secure === true && isHttps === false) {\n    throw new Error(\n      `iron-session: Can't use secure cookies when not in https. See usage at https://github.com/vvo/iron-session/`,\n    );\n  }\n\n  const options: Required<IronSessionOptions> = {\n    ...defaultOptions,\n    ...userSessionOptions,\n    cookieOptions: {\n      ...defaultOptions.cookieOptions,\n      ...(userSessionOptions.cookieOptions || {}),\n    },\n  };\n\n  // if the user did not set the secure flag themselves, we automatically configure it\n  if (userSessionOptions.cookieOptions?.secure === undefined) {\n    options.cookieOptions.secure = isHttps;\n  }\n\n  if (options.ttl === 0) {\n    // ttl = 0 means no expiration\n    // but in reality cookies have to expire (can't have no max-age)\n    // 2147483647 is the max value for max-age in cookies\n    // see https://stackoverflow.com/a/11685301/147079\n    options.ttl = 2147483647;\n  }\n\n  if (\n    userSessionOptions.cookieOptions &&\n    \"maxAge\" in userSessionOptions.cookieOptions\n  ) {\n    // session cookie, do not set maxAge, consider token as infinite\n    if (userSessionOptions.cookieOptions.maxAge === undefined) {\n      options.ttl = 0;\n    } else {\n      options.cookieOptions.maxAge = computeCookieMaxAge(\n        userSessionOptions.cookieOptions.maxAge,\n      );\n    }\n  } else {\n    options.cookieOptions.maxAge = computeCookieMaxAge(options.ttl);\n  }\n\n  const sealFromCookies = parseCookie(req.headers.cookie || \"\")[\n    options.cookieName\n  ];\n\n  const session =\n    sealFromCookies === undefined\n      ? {}\n      : await unsealData(sealFromCookies, passwordsAsMap, options.ttl);\n\n  Object.defineProperties(session, {\n    save: {\n      value: async function save() {\n        if (res.headersSent === true) {\n          throw new Error(\n            `iron-session: Cannot set session cookie: session.save() was called after headers were sent. Make sure to call it before any res.send() or res.end()`,\n          );\n        }\n        const seal = await sealData(session, passwordsAsMap, options.ttl);\n        const cookieValue = serializeCookie(\n          options.cookieName,\n          seal,\n          options.cookieOptions,\n        );\n\n        if (cookieValue.length > 4096) {\n          throw new Error(\n            `iron-session: Cookie length is too big ${cookieValue.length}, browsers will refuse it. Try to remove some data.`,\n          );\n        }\n\n        addToCookies(cookieValue, res);\n      },\n    },\n    destroy: {\n      value: function destroy() {\n        Object.keys(session).forEach((key) => {\n          // @ts-ignore See comment on the IronSessionData interface\n          delete session[key];\n        });\n\n        const cookieValue = serializeCookie(options.cookieName, \"\", {\n          ...options.cookieOptions,\n          maxAge: 0,\n        });\n        addToCookies(cookieValue, res);\n      },\n    },\n  });\n\n  return session as IronSession;\n}\n\nfunction addToCookies(cookieValue: string, res: ServerResponse) {\n  let existingSetCookie =\n    (res.getHeader(\"set-cookie\") as string[] | string) ?? [];\n  if (typeof existingSetCookie === \"string\") {\n    existingSetCookie = [existingSetCookie];\n  }\n  res.setHeader(\"set-cookie\", [...existingSetCookie, cookieValue]);\n}\n\nfunction computeCookieMaxAge(ttl: number) {\n  // The next line makes sure browser will expire cookies before seals are considered expired by the server.\n  // It also allows for clock difference of 60 seconds maximum between server and clients.\n  // It also makes sure to expire the cookie immediately when value is 0\n  return ttl - timestampSkewSec;\n}\n\nexport async function unsealData(\n  seal: string,\n  password: password,\n  ttl: number = fourteenDaysInSeconds,\n): Promise<IronSessionData> {\n  const passwordsAsMap = normalizeStringPasswordToMap(password);\n  const { sealWithoutVersion, tokenVersion } = parseSeal(seal);\n\n  try {\n    const data = await Iron.unseal(sealWithoutVersion, passwordsAsMap, {\n      ...Iron.defaults,\n      ttl: ttl * 1000,\n    });\n\n    if (tokenVersion === 2) {\n      return data;\n    }\n\n    return {\n      ...data.persistent,\n    };\n  } catch (error) {\n    if (error instanceof Error) {\n      if (\n        error.message === \"Expired seal\" ||\n        error.message === \"Bad hmac value\" ||\n        error.message === \"Cannot find password: \" ||\n        error.message === \"Incorrect number of sealed components\"\n      ) {\n        // if seal expired or\n        // if seal is not valid (encrypted using a different password, when passwords are badly rotated) or\n        // if we can't find back the password in the seal\n        // then we just start a new session over\n        return {};\n      }\n    }\n\n    throw error;\n  }\n}\n\nfunction parseSeal(seal: string): {\n  sealWithoutVersion: string;\n  tokenVersion: number | null;\n} {\n  if (seal[seal.length - 2] === versionDelimiter) {\n    const [sealWithoutVersion, tokenVersionAsString] =\n      seal.split(versionDelimiter);\n    return {\n      sealWithoutVersion,\n      tokenVersion: parseInt(tokenVersionAsString, 10),\n    };\n  }\n\n  return { sealWithoutVersion: seal, tokenVersion: null };\n}\n\nexport async function sealData(\n  data: IronSessionData,\n  password: password,\n  ttl: number = fourteenDaysInSeconds,\n) {\n  const passwordsAsMap = normalizeStringPasswordToMap(password);\n\n  const mostRecentPasswordId = Math.max(\n    ...Object.keys(passwordsAsMap).map((id) => parseInt(id, 10)),\n  );\n\n  const passwordForSeal = {\n    id: mostRecentPasswordId.toString(),\n    secret: passwordsAsMap[mostRecentPasswordId],\n  };\n\n  const seal = await Iron.seal(data, passwordForSeal, {\n    ...Iron.defaults,\n    ttl: ttl * 1000,\n  });\n\n  return `${seal}${versionDelimiter}${currentMajorVersion}`;\n}\n\nfunction normalizeStringPasswordToMap(password: password) {\n  return typeof password === \"string\" ? { 1: password } : password;\n}\n"],
+  "mappings": "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",
+  "names": []
+}