@nuxt/docs-nightly 5.0.0-29824817.35cc2cb5 → 5.0.0-29824891.6f2fc18e

package/1.getting-started/18.upgrade.md

@@ -396,6 +396,52 @@ Server auto-imports resolve to `nuxt/server` too, so a project that leaves them
 Learn what the surface covers, and what it means for module authors.
 ::
 
+### Sessions Come From `nuxt/server`
+
+🚦 **Impact Level**: Medium
+
+#### What Changed
+
+`useSession`, `getSession`, `updateSession` and `clearSession` are now part of [`nuxt/server`](/docs/guide/going-further/server-imports#sessions), and are what the auto-imported names resolve to. They seal the session with `iron-webcrypto` on web-standard `Request` and `Response`, so they run under any [`server.builder`](/docs/guide/going-further/builders) rather than only under Nitro.
+
+A session issued by the h3 helpers does not unseal with these, and the default cookie name is `nuxt-session` rather than `h3`. Everyone signed in before the upgrade gets a fresh, empty session once.
+
+A `password` is no longer required. Without one, the session is sealed with a secret derived from [`appSecret`](/docs/guide/going-further/runtime-config#application-secret), which `NUXT_APP_SECRET` sets:
+
+```diff [server/api/me.ts]
+  export default defineEventHandler(async (event) => {
+-   const session = await useSession<{ user?: string }>(event, {
+-     password: process.env.NUXT_SESSION_PASSWORD!,
+-   })
++   const session = await useSession<{ user?: string }>(event)
+    return { user: session.data.user }
+  })
+```
+
+Passing a `password` of at least 32 characters still seals with that instead.
+
+To keep h3's implementation, import it explicitly:
+
+```diff [server/api/me.ts]
++ import { useSession } from 'nitro/h3'
+
+  export default defineEventHandler(async (event) => {
+    const session = await useSession(event, { password: process.env.NUXT_SESSION_PASSWORD! })
+    return { user: session.data.user }
+  })
+```
+
+#### Migration Steps
+
+1. Plan for existing sessions ending: users are signed out once, on the deploy that upgrades them.
+2. Where you relied on h3-specific options (`sessionHeader`, `crypto`, `seal`), either import `useSession` from `nitro/h3` or move to the `nuxt/server` equivalents: `name`, `maxAge` and `cookie`.
+3. Set `NUXT_APP_SECRET` in every deployed environment if you drop `password`; in development Nuxt generates one.
+4. Set the cookie name to `h3` only if you also keep h3's helpers; the two implementations should not share a cookie.
+
+::read-more{to="/docs/guide/going-further/server-imports#sessions"}
+Learn what the session helpers cover.
+::
+
 ### Migration to Nitro v3
 
 🚦 **Impact Level**: Significant

package/3.guide/6.going-further/10.runtime-config.md

@@ -35,7 +35,7 @@ Public runtime config is accessible in Vue templates with `$config.public`.
 
 ### Application Secret
 
-Nuxt provides a private `runtimeConfig.appSecret` as the application's root secret. Modules and server features can use it to derive their own secrets. The value defaults to an empty string, is only available on the server, and you can set it with `NUXT_APP_SECRET` without declaring the key in `nuxt.config`.
+Nuxt provides a private `runtimeConfig.appSecret` as the application's root secret. Modules and server features derive their own secrets from it with [`deriveSecret`](/docs/guide/going-further/server-imports#deriving-secrets), and the [session helpers](/docs/guide/going-further/server-imports#sessions) seal with one by default. The value defaults to an empty string, is only available on the server, and you can set it with `NUXT_APP_SECRET` without declaring the key in `nuxt.config`.
 
 Generate a secret that contains at least 32 random bytes:
 

package/3.guide/6.going-further/5.server-imports.md

@@ -42,11 +42,13 @@ This code can run under `@nuxt/nitro-server` and under `@nuxt/vite-server`, and
 | `setResponseStatus` | Set the response status and reason phrase. |
 | `setResponseHeader`, `setResponseHeaders` | Set response headers. |
 | `sendRedirect` | Redirect the request. |
+| `useSession`, `getSession`, `updateSession`, `clearSession` | Read and write a [sealed session cookie](#sessions). |
+| `deriveSecret` | A purpose-specific secret [derived from `appSecret`](#deriving-secrets). |
 | `getRouteRules` | The [route rules](/docs/guide/concepts/rendering#route-rules) matched for the request. |
 | `useRuntimeConfig` | The server's [runtime configuration](/docs/guide/going-further/runtime-config). |
 | `toNuxtRequestEvent` | The event in the shape the server runtime provides. |
 
-Types are exported alongside the utilities: `RequestEvent`, `RequestEventContext`, `NuxtRequestEvent`, `EventHandler`, `AppRouteRules`, `ServerRoutes`, `NuxtError`, `NuxtErrorDetails`, `NuxtErrorJSON` and `NuxtErrorLike`.
+Types are exported alongside the utilities: `RequestEvent`, `RequestEventContext`, `NuxtRequestEvent`, `EventHandler`, `AppRouteRules`, `ServerRoutes`, `NuxtError`, `NuxtErrorDetails`, `NuxtErrorJSON`, `NuxtErrorLike`, `Session`, `SessionConfig`, `SessionData`, `SessionEvent`, `SessionManager`, `SessionPassword` and `SessionUpdate`.
 
 These names are [auto-imported](/docs/directory-structure/server) in server code, so the import statement above is optional. Writing it keeps the file working in a project with server auto-imports off, and is what a module should do.
 
@@ -78,6 +80,44 @@ export default defineEventHandler(async (event) => {
 
 `NuxtRequestEvent` is the same request in the shape the configured builder provides, which is h3's `H3Event` under `@nuxt/nitro-server`. You can get a type-safe version of the event for the server builder you're using by calling `toNuxtRequestEvent(event)`.
 
+## Sessions
+
+`useSession` reads the session for the request, sealing a new one into a cookie when there is none to read. The data is sealed with [iron](https://github.com/brc-dd/iron-webcrypto), so it lives in the cookie rather than in server storage, and the cookie defaults to `httpOnly`, `secure`, `sameSite: 'lax'` and `path: '/'`.
+
+```ts [server/api/visits.ts]
+import { defineEventHandler, useSession } from 'nuxt/server'
+
+export default defineEventHandler(async (event) => {
+  const session = await useSession<{ visits: number }>(event)
+  await session.update(data => ({ visits: (data.visits ?? 0) + 1 }))
+  return { visits: session.data.visits }
+})
+```
+
+With no `password`, the session is sealed with a secret derived from the application's [`appSecret`](/docs/guide/going-further/runtime-config#application-secret), so `NUXT_APP_SECRET` is the only thing to set. Pass a `password` of at least 32 characters to seal with a secret of your own instead. Set `maxAge` (in seconds) to expire both the cookie and the sealed value, `name` to change the cookie name from `nuxt-session`, and `cookie` to override any cookie attribute.
+
+The session is unsealed once per request, so `getSession` may be called from as many places as you like. `updateSession` and `clearSession` are the same operations without the manager object.
+
+### Deriving Secrets
+
+`deriveSecret(purpose)` resolves a secret for one purpose from `appSecret`: 32 bytes, hex-encoded, stable for as long as `appSecret` is unchanged, and distinct for every purpose. It is what the session helpers use, and what a module should use in place of asking for a secret of its own. Namespace the purpose to what owns it.
+
+```ts
+import { deriveSecret } from 'nuxt/server'
+
+const password = await deriveSecret('my-module:tokens')
+```
+
+It throws a `500` naming `NUXT_APP_SECRET` when `appSecret` is unset or shorter than 32 characters.
+
+::note
+h3 ships session helpers of the same names, reachable as `import { useSession } from 'nitro/h3'`. They are a separate implementation and are not interchangeable with these: they default to the `h3` cookie name rather than `nuxt-session`, take their own configuration, and a session one of them issues will not unseal with the other.
+::
+
+::warning
+The session travels in the cookie, so it is limited to what a browser will accept. Writing a session that serialises to more than 4096 bytes throws; keep large data server-side and reference it from the session by id.
+::
+
 ## Reaching Past the Surface
 
 `nuxt/server` isn't a re-export of h3, so if you need something else that h3 and Nitro offer, such as the server lifecycle (`definePlugin`, `defineErrorHandler` and the Nitro app hooks), you would import it directly.
@@ -94,7 +134,7 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
-That works for any h3 helper that only reads the request: `readValidatedBody`, `getValidatedQuery`, `getRouterParam`, `getRouterParams`, `getRequestIP`, `assertMethod`, and the session helpers (`useSession`, `getSession`, `updateSession`, `clearSession`).
+That works for any h3 helper that only reads the request: `readValidatedBody`, `getValidatedQuery`, `getRouterParam`, `getRouterParams`, `getRequestIP` and `assertMethod`.
 
 A helper that needs the runtime's own event gets it from `toNuxtRequestEvent`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29824817.35cc2cb5",
+  "version": "5.0.0-29824891.6f2fc18e",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",