Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

iron-session

/iron-session

Przechowuje sesje logowania w zaszyfrowanych, podpisanych ciasteczkach dzięki iron-session, bez bazy sesji, w aplikacjach Next.js i Node.js z przepływem logowania, ochroną stron i rotacją hasła.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Przechowuje sesje logowania w zaszyfrowanych, podpisanych ciasteczkach dzięki iron-session, bez bazy sesji, w aplikacjach Next.js i Node.js z przepływem logowania, ochroną stron i rotacją hasła.

Oryginalny opis (EN)

Stores login sessions in encrypted, signed cookies with iron-session, so a Next.js or Node.js app needs no session database. Use when a user asks for cookie-based session auth, stateless sessions, a login and logout flow with the App Router, protecting pages with a session, rotating the session password, or upgrading iron-session from v8 to v9.

Jak działa

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Sekcje z nagłówków SKILL.md, w oryginale · 150 linii, 1 006 słów
Podgląd SKILL.md
---
name: iron-session
description: >-
  Stores login sessions in encrypted, signed cookies with iron-session, so a Next.js or Node.js app needs no session database. Use when a user asks for cookie-based session auth, stateless sessions, a login and logout flow with the App Router, protecting pages with a session, rotating the session password, or upgrading iron-session from v8 to v9.
license: Apache-2.0
compatibility: 'iron-session 9.x needs Node.js 22.13 or newer (ESM-only). Works with Next.js App Router and API routes, Express, Hono, Bun, Deno and Cloudflare Workers.'
metadata:
  author: terminal-skills
  version: "1.1.0"
  category: development
  tags: "iron-session, sessions, nextjs, cookies, auth"
  repository: https://github.com/vvo/iron-session
---

# iron-session

## Overview

iron-session keeps the session data inside an encrypted and signed cookie. The server decrypts it on each request, so no database, Redis or network call is involved. The same idea as Rails cookie sessions.

Version 9 (current: 9.0.1) needs Node.js 22.13+ and is ESM-only; `require()` still works on Node 22.13+. On older Node, install `iron-session@8`. v9 reads v8 cookies and v8 reads v9 cookies, so a deploy can be rolled back without signing users out.

Two changes when upgrading from v8:

- Store timestamps as numbers (`Date.now()`), not `Date` objects. v9 throws on a `Date` and names the field.
- Session reads are typed `Partial<T>`: a first visit, an expired cookie or a destroyed session is an empty object. Write `session.user?.id`, not `session.user.id`.

## Instructions

### Step 1: Install and configure

```bash
npm install iron-session
openssl rand -base64 32     # value for SESSION_PASSWORD (at least 32 characters)
```

```typescript
// lib/session.ts
import { getIronSession, type SessionOptions } from 'iron-session'
import { cookies } from 'next/headers'

export interface SessionData {
  userId?: string
  role?: 'admin' | 'member'
  loggedInAt?: number          // timestamp, not a Date
}

export const sessionOptions: SessionOptions = {
  password: process.env.SESSION_PASSWORD!,
  cookieName: 'shopfront_session',
  ttl: 60 * 60 * 24 * 7,       // seal lifetime in seconds (default is 14 days)
  cookieOptions: { secure: process.env.NODE_ENV === 'production' },
}

export async function getSession() {
  return getIronSession<SessionData>(await cookies(), sessionOptions)
}
```

`password` and `cookieName` are the only required options. The defaults for `cookieOptions` are already `httpOnly: true`, `sameSite: 'lax'`, `path: '/'` and `secure: true`; the cookie `maxAge` follows `ttl` (minus 60 seconds), so you rarely set it yourself.

### Step 2: Log in and out

```typescript
// app/actions/auth.ts
'use server'
import { redirect } from 'next/navigation'
import { getSession } from '@/lib/session'

export async function login(formData: FormData) {
  const user = await verifyCredentials(
    String(formData.get('email')),
    String(formData.get('password')),
  )
  if (!user) return { error: 'Wrong email or password' }

  const session = await getSession()
  session.userId = user.id
  session.role = user.role
  session.loggedInAt = Date.now()
  await session.save()          // must be awaited before the response is sent
  redirect('/dashboard')
}

export async function logout() {
  const session = await getSession()
  session.destroy()             // synchronous; removes the cookie
  redirect('/login')
}
```

`destroy()` is terminal: a `save()` after it is ignored, and writing fields back and then saving throws.

### Step 3: Protect data where it is read

```tsx
// app/dashboard/page.tsx
import { redirect } from 'next/navigation'
import { getSession } from '@/lib/session'

export default async function DashboardPage() {
  const session = await getSession()
  if (!session.userId) redirect('/login')
  const orders = await db.order.findMany({ where: { userId: session.userId } })
  return <OrderList orders={orders} />
}
```

Check the session in each Server Component, Server Action or Route Handler that touches protected data. A layout does not protect the pages under it, and neither does a redirect in `proxy.ts`.

### Other runtimes

```typescript
// Express / Node http / Next.js API routes
const session = await getIronSession<SessionData>(req, res, sessionOptions)

// Hono, Bun, Deno, Workers: any web-standard Request/Response
import { getIronSession, webCookies } from 'iron-session'
const session = await getIronSession<SessionData>(webCookies(request, response), sessionOptions)

// Next.js proxy.ts (middleware.ts before Next 16): needs the adapter or the cookie is not saved
import { getIronSession, nextProxyCookies } from 'iron-session'
const response = NextResponse.next()
const session = await getIronSession<SessionData>(nextProxyCookies(request, response), sessionOptions)
```

### Rotating the password and logging problems

```typescript
password: { 2: process.env.SESSION_PASSWORD_NEW!, 1: process.env.SESSION_PASSWORD_OLD! },
onUnsealError: (reason, error) => {
  if (reason !== 'expired') console.warn('session cookie rejected', reason, error)
},
```

New cookies use the highest-numbered key; old cookies still open with the old one. `reason` is `"expired"`, `"invalid"` or `"unknown-password"`. A burst of `unknown-password` usually means a rotation went wrong.

## Examples

### Example 1: Add login to a Next.js 16 app

**User prompt:** "Add email and password login to my App Router app and keep the user logged in for a week, with no database for sessions."

Install `iron-session`, put `SESSION_PASSWORD` (from `openssl rand -base64 32`) in `.env.local`, create `lib/session.ts` as in Step 1 with `ttl: 604800`, and write `login`/`logout` Server Actions as in Step 2. Result: after login the browser holds one `shopfront_session` cookie (HttpOnly, SameSite=Lax, about 7 days); `/dashboard` reads `session.userId` on the server and redirects to `/login` when it is missing.

### Example 2: Upgrade from v8 and see why users get logged out

**User prompt:** "I moved to iron-session 9 and TypeScript now complains about session.user.id. Also some users get signed out after we changed the secret."

Change reads to `session.user?.id`, replace `new Date()` with `Date.now()`, and run on Node 22.13+. For the secret, move to the object form `{ 2: newSecret, 1: oldSecret }` so old cookies still open, and add `onUnsealError` to log `unknown-password` events. Result: type errors disappear and existing sessions survive the rotation.

## Guidelines

- The password must be at least 32 characters and live in an environment variable, never in the repository.
- Cookies over 4096 bytes make `save()` throw. Keep about 3 KB at most: store an id and look the rest up in your database. `chunk: true` splits across at most 4 cookies, but every cookie is sent with every request, so prefer the id approach.
- Stateless means no instant revocation. Check an `isBlocked` flag or a session version in the database on sensitive requests; deleting the cookie in the browser is all `destroy()` does.
- `ttl: 0` makes the seal never expire and never revocable; do not use it for authentication.
- An unreadable cookie (tampered, expired, old password) silently becomes an empty session, not an error. Log with `onUnsealError`.
- There is no built-in validation of the session shape. After you change `SessionData`, old cookies still decrypt into the old shape: validate in your `getSession()` wrapper and call `destroy()` if it does not match.
- With Next.js `cacheComponents`, read the session inside a `<Suspense>` boundary and never inside `use cache`.
- `sealData` and `unsealData` seal any value with a TTL, which suits magic links.
- Use it with an HTTPS site in production. Add CSRF protection for state-changing routes that are not Server Actions.
Pliki w paczce (2)
  • SKILL.md 8 KB
  • _scores.json 2 KB

Wersje

W bazie nie ma innych skilli o nazwie iron-session.

Migawka bazy z 13.11.2026 · wersja paczki a9a1ad4387e3 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100supabase-auth-ssr
    Konfiguruje Supabase Auth z @supabase/ssr w Next.js 15 App Router: klienty, sesje w cookies, zapytania z RLS, magic link, OAuth, reset hasła i ochrona tras.
  • 100security
    Buduje i wzmacnia uwierzytelnianie w Phoenix: logowanie OAuth, hasła, sesje i uprawnienia, z ochroną przed typowymi błędami.
  • 100haven-auth
    Loguje do stosu worktree jako admin lub zasiany użytkownik poleceniem haven browser login --as, zapisując plik storage-state Playwright i nigdy nie wypisując hasła.
  • 100verify-login-logout
    Dowodzi, że logowanie prowadzi we właściwe miejsce, wylogowanie kończy sesję, a chroniona strona odsyła do logowania, oraz że wygasła sesja prosi o ponowne zalogowanie.
  • 100sfnext-authentication
    Obsługuje serwerowe uwierzytelnianie i sesje Storefront Next: tokeny SLAS gościa i zalogowanego, ciasteczka httpOnly, middleware auth.server.ts, logowanie, scalanie koszyka i odzyskiwanie po błędzie 401.
  • 100phx-init
    Inicjalizuje plugin Elixir w projekcie, instalując Iron Laws i reguły aktywacji przy konfiguracji lub aktualizacji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.