iron-session
🛠Secure, stateless, and cookie-based session library for JavaScript
MIT License
Bot releases are visible (Hide)
We've updated the types and examples for destroy from session.destroy() => Promise<void> to session.destroy() => void. Destroy is not asynchronous, it only removes the session cookie.
Published by vvo 11 months ago
The v8 of iron-session focuses on reducing its API surface and bringing compatibility with the Next.js App Router.
As long as you make the required code changes, this upgrade will not disconnect your customers once deployed.
Instead of multiple opinionated wrappers (withIronSess..) There's now a single method to get sessions: getIronSession().
Use it like this:
import { getIronSession } from "iron-session";
const session = getIronSession(req, res, { password: "...", cookieName: "..." });
// or, in App Router:
const session = getIronSession(cookies(), { password: "...", cookieName: "..." });
Read more in the README: https://github.com/vvo/iron-session#usage.
Have a look at our new examples:
New features:
- App Router compatibility
-
updateConfigmethod to change a session configuration for the nextsave()ordestroy() - Single entry point, no more
/next,/edge, ..
BREAKING CHANGES:
- We've removed support for Node.js < 18
- We've removed
withIronSessionApiRoute,withIronSessionSsr,ironSession - added support
Gigantic thanks to:
- @brc-dd for creating https://github.com/brc-dd/iron-webcrypto, doing most of the work of the b8 branch and being of great help while designing the API!
- @renchris for making the adapter to support server components, server actions and route handlers.
Published by vvo almost 3 years ago
This is a BREAKING CHANGE (Major) release.
I did a full rewrite of the library in TypeScript, both as an exercise for me and to provide better types by default for consumers of the library. Since it was a full rewrite I took the opportunity to solve most of the issues from the GitHub repository along with feature requests.
Hope you like it. You'll find a migration guide in these changes.
Changes:
- The library was renamed to
iron-session(since it works on all Node.js HTTP frameworks) - TypeScript: We have better types and you can now easily type check your session data (see usage in README). Fixes #369. Fixes #368.
- You can access and set session data directly on req.session.* instead of having to call .get()/.set()/.unset()
- get/set/unset methods were removed
- The library exposes different wrappers for Next.js API Routes, Next.js getServerSideProps, and Express.js middleware (see migration guide)
- List of passwords (rotation) must now be passed as objects like {1: 'password1', 2: 'password2'}
- When upgrading previous sessions will be kept which means that you can safely upgrade and your users will not lose their data or be logged out
- We now expose sealData/unsealData methods to create magic links and impersonation flows.
iron-storeis no more used. - We have updated the examples (Next.js, Next.js with TypeScript and Express.js) to use the new API
- The library is now published as an ES module along with CommonJS
- We now warn on bad usage (http + secure or save called after the response was sent). Fixes #8
- We now automatically set the cookie to secure or not secure based on the protocol.
- You can now have "session cookies" by passing {cookiesOptions: {maxAge: undefined}}. Fixes #340
- We handle the case where the cookie has been tampered with (we generate a new one). Fixes #380
Migration guide:
1. Uninstall next-iron-session and install iron-session:
npm remove next-iron-session
npm add iron-session
2. Change import paths in your code:
Before:
import { withIronSession } from "next-iron-session";
After:
import { withIronSessionApiRoute, withIronSessionSsr } from "iron-session/next";
import { ironSession } from "iron-session/express";
3. Change your code to use the new API:
Before:
req.session.set("user", { name: "John" });
const user = req.session.get("user");
req.session.unset("user");
After:
req.session.user = { name: "John" };
const user = req.session.user; // or use req.session.user directly
delete req.session.user;
4. (Optional) Remove secure flag from your options
The cookie secure flag is now automatically set based on http/https unless you want to change it.
Before:
withIronSession(handler, {
password: "complex_password_at_least_32_characters_long",
cookieName: "myapp_cookiename",
// if your localhost is served on http:// then disable the secure flag
cookieOptions: {
secure: process.env.NODE_ENV === "production",
},
});
After:
withIronSessionApiRoute(handler, {
password: "complex_password_at_least_32_characters_long",
cookieName: "myapp_cookiename",
});
5. (Optional) Change the format of your password
If you were passing down a list of passwords (for password rotations) then you need to update it to:
Before:
withIronSession(handler, {
password: [
{
id: 2,
password: "complex_password_at_least_32_characters_long",
},
{
id: 1,
password: "complex_password_at_least_32_characters_long",
},
],
});
After:
withIronSessionApiRoute(handler, {
password: {
2: "another_password_at_least_32_characters_long",
1: "complex_password_at_least_32_characters_long",
},
});
6. (Optional) Replace iron-store usage with sealData/unsealData
If you were using iron-store to create seals for magic links or impersonation flows then you can replace it with sealData/unsealData.
Because we no more needed get/set/unset methods. We completely ditched the iron-store library that was initially built for next-iron-session needs.
Before:
const store = await ironStore({
password: "complex_password_at_least_32_characters_long",
ttl: 14 * 24 * 60 * 60 * 1000
});
store.set("user", { name: "John" });
const seal = await store.seal();
// later on, in a different file:
const store = await ironStore({
seal: req.query.seal,
password: "complex_password_at_least_32_characters_long",
ttl: 14 * 24 * 60 * 60 * 1000
});
const user = store.get("user);
After:
import { sealData } from "iron-session";
const store = {
user: { name: "John" },
};
const seal = await sealData(store, {
password: "complex_password_at_least_32_characters_long",
// ttl is always 14 days by default
});
// later on, in a different file:
import { unsealData } from "iron-session";
const store = await unseatData(req.query.seal, {
password: "complex_password_at_least_32_characters_long",
});
const user = store.user;
5. (Optional) Check the best way to use TypeScript with the library
Have a look at the README to know how to do that, here: https://github.com/vvo/iron-session#session-wrappers
Enjoy!
Published by vvo over 4 years ago
4.0.0 (2020-05-01)
Features
- API: expose ironSession (express), applySession, cookieName required (5b7c3d1), closes #54 #54 #9 #41
- API: remove setFlash (3320ccd), closes #53
- cookieName: enforce cookieName option (c016fec), closes #54
BREAKING CHANGES
-
API: - req.session.setFlash was removed, if you were using this please comment on
GitHub -
API: - you need to import withIronSession as a named export:
before: import withIronSession from "next-iron-session"
after: import { withIronSession } from "next-iron-session" -
cookieName: cookieName is now mandatory, to avoid issues of shared
cookieNames in examples etc..
