# Server (/docs/reference/server) ```ts import { … } from "@monarcode/session-kit/server"; ``` Guide: [Server sessions](/docs/server-rendering/server-sessions). ## Functions [#functions] ### createServerAuth [#createserverauth] Creates the server side of Session kit ([`ServerAuth`](#serverauth)). It keeps both tokens and the user in an encrypted, `httpOnly` cookie, so page scripts never see the refresh token. ## Types [#types] ### ClientCredentials [#clientcredentials] The access token as your server gives it to the browser, from `serverAuth.clientCredentials` in `@monarcode/session-kit/server`. `expiresIn` counts from when the server answered, so the browser's clock doesn't matter. ### CookieJar [#cookiejar] Reads and writes one request's cookies, for `createServerAuth`'s methods. The framework adapters, such as `nextJar` and `startJar`, build one. Elsewhere, wrap the request's cookies and the response's `Set-Cookie`. ### CookieJar Reads and writes one request's cookies, for `createServerAuth`'s methods. The framework adapters, such as `nextJar` and `startJar`, build one. Elsewhere, wrap the request's cookies and the response's `Set-Cookie`. Make a new jar for each request, and pass it to every call while handling that request, so they share one refresh and see each other's writes. Never keep one at module level, or one request's session would show in the next. | Prop | Type | Description | | ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get` | `function` | Returns the request's cookie `name`, or `undefined` when it has none. | | `set` | `function` | Sets cookie `name` on the response. | | `delete` | `function` | Removes cookie `name`, with the attributes it was set with. | | `writable` | `union` | Whether the response can still set cookies. It's `false` where the framework can't, such as while a Next.js Server Component renders. Then nothing is refreshed or saved, and calls that would write reject, as each `serverAuth` method says. | ### CookieOptions [#cookieoptions] The session cookie's attributes, as [`CookieJar`](#cookiejar)'s `set` and `delete` receive them. Every framework's cookie API takes this shape, or maps from it in a line. ### CookieOptions The session cookie's attributes, as CookieJar's `set` and `delete` receive them. Every framework's cookie API takes this shape, or maps from it in a line. | Prop | Type | Description | | ---------- | -------- | ---------------------------------------------------------------- | | `httpOnly` | `true` | Always `true`: page scripts can't read the session cookie. | | `secure` | `union` | Whether the cookie is sent over HTTPS only. | | `sameSite` | `union` | Which cross-site requests carry the cookie. | | `path` | `string` | The paths that receive the cookie. | | `domain?` | `string` | The domain that receives the cookie, or none for this host only. | | `maxAge?` | `number` | Lifetime in seconds. Absent when deleting. | ### RefreshIfDueOptions [#refreshifdueoptions] Options for [`ServerAuth`](#serverauth)'s `refreshIfDue`. ### RefreshIfDueOptions Options for ServerAuth's `refreshIfDue`. | Prop | Type | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `within?` | `number` | Refreshes when the access token expires within this many seconds, so it lasts through the request. Keep it well below the token's lifetime: a token that lives less than `within` is refreshed on every request. Default: `60` | ### RequestAuth [#requestauth] One request's session, shaped like a client. Get it from `serverAuth.forRequest(jar)`, and pass it to code that expects a client, such as `createAuthFetch` from `@monarcode/session-kit/http`. Make one per request, never at module level. ### ServerAuth [#serverauth] The server side of Session kit, from [`createServerAuth`](#createserverauth). It keeps the session in an encrypted cookie. Each method takes the request's [`CookieJar`](#cookiejar), and `forRequest(jar)` gives one request's session shaped like a client ([`RequestAuth`](#requestauth)). ### ServerAuthOptions [#serverauthoptions] Options for [`createServerAuth`](#createserverauth). `user`, `refresh`, `revoke`, `maxAge` and `debug` work as they do for `createAuth`. ### ServerAuthOptions Options for createServerAuth. `user`, `refresh`, `revoke`, `maxAge` and `debug` work as they do for `createAuth`. | Prop | Type | Description | | -------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Names this auth and its cookie, `.session`, which is split into `.session.0…n` when large. Up to 64 letters, digits, `_` or `-`. | | `user` | `Src` | Where the user comes from: a schema that checks the `user` passed to `signIn`, or `fromAccessToken(…)`. The cookie is trusted once sealed, but `signIn` doesn't check its input with your backend (ServerAuth says what to do). | | `secret` | `union` | The key that seals the cookie, with AES-256-GCM: at least 32 random characters, kept out of your code and the browser. Pass a list to rotate keys. The first seals, and any of them opens, so sessions survive a new secret. A cookie none of them opens reads as signed out. It's checked when a method first runs, not at creation, so build tools that load your module without it, such as `next build`, still work. Without a valid secret, every method rejects with `INVALID_OPTIONS`, and `forRequest`'s view reports `unavailable`. | | `refresh?` | `RefreshFn>>` | Exchanges a refresh token for new tokens, as RefreshFn says. | | `revoke?` | `RevokeFn` | Asks your backend to revoke the tokens after `signOut` (RevokeFn). | | `maxAge?` | `number` | How long the cookie lasts, in seconds. Each save starts it again. Default: 30 days. | | `cookie?` | `SessionCookieOptions` | The session cookie's attributes (SessionCookieOptions). Default: each attribute's own. | | `clientCredentials?` | `union` | Lets `clientCredentials` give the access token to your own page scripts, through a function you expose. The refresh token never leaves the server. Without it, `clientCredentials` rejects with `INVALID_OPTIONS`. Default: `false` | | `debug?` | `union` | Logs what auth does on the server, like `createAuth`'s `debug` option. | ### SessionCookieOptions [#sessioncookieoptions] The session cookie's attributes: the `cookie` option of [`ServerAuthOptions`](#serverauthoptions). The cookie is always `httpOnly`. ### SessionCookieOptions The session cookie's attributes: the `cookie` option of ServerAuthOptions. The cookie is always `httpOnly`. | Prop | Type | Description | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `secure?` | `union` | Sends the cookie over HTTPS only. Turn it off only for plain-http development on `localhost`. Default: `true` | | `sameSite?` | `union` | Which cross-site requests send the cookie. `"none"` needs `secure`, or `createServerAuth` throws `INVALID_OPTIONS`. Default: `"lax"` | | `path?` | `string` | The paths the cookie is sent to. Default: `"/"` | | `domain?` | `string` | Shares the cookie with subdomains. Default: this host only. |