# Fastify sessions

`@keenauth/node/bff` adds sign-in to a Fastify 5 application. Your server is the OAuth client and keeps every token on the server. The browser gets only an encrypted, HttpOnly session cookie and never sees an access, refresh or ID token. This is the backend-for-frontend (BFF) pattern. The package does not import Fastify, so it adds no dependency. It is not published to npm yet.

To protect an API that receives bearer tokens instead, see [Protecting your API](/docs/sdk/protect-api).

## Before you start

1. In the dashboard, create a web application in your environment.
2. Choose client authentication: a client secret (`client_secret_basic`) or `private_key_jwt` with a key pair whose public key you register on the application. `private_key_jwt` is recommended, because no shared secret leaves your server.
3. Add the redirect URI `https://app.acme.example/auth/callback` and the post-logout redirect URI `https://app.acme.example/`.
4. Generate a cookie secret of at least 32 characters, for example with `openssl rand -base64 32`. Keep it in your secret store, not in the repository.

## Set up

```ts
import Fastify from "fastify";
import { createBff, fastifyRequireAuth, fastifySession } from "@keenauth/node/bff";

const bff = createBff({
  issuer: "https://acme.eu.keenauth.app", // your environment's issuer, exactly
  clientId: "app_01j9zzzzzzzzzzzzzzzzzzzz",
  clientAuth: { method: "client_secret_basic", clientSecret: process.env.KEENAUTH_CLIENT_SECRET! },
  appBaseUrl: "https://app.acme.example",
  secret: process.env.KEENAUTH_COOKIE_SECRET!,
});

const app = Fastify();
fastifySession(app, bff); // on the root instance, so it applies to every route

app.get("/orders", { preHandler: fastifyRequireAuth(bff) }, async (request) => {
  return `Signed in as ${request.keenauth!.session!.user.email}`;
});
```

With `private_key_jwt`, pass the private key instead of the secret: `clientAuth: { method: "private_key_jwt", privateKey: readFileSync("bff-key.pem", "utf8") }`. The SDK signs a new client assertion for every request to the token and PAR endpoints. If the key lives in a KMS or HSM, pass `clientAuth: { method: "private_key_jwt", assertion }`, where `assertion()` returns a new signed client assertion each time. The [Express page](/docs/sdk/express) describes the assertion and the supported algorithms.

Call `fastifySession` on the root instance. Inside an encapsulated plugin it applies only to that plugin's routes.

`appBaseUrl` is the public address of your app. The SDK builds the redirect URI and every redirect from it, never from the request's `Host` or `X-Forwarded-*` headers, so the `trustProxy` option does not affect it. Plain `http` is accepted only for `localhost`.

The options are checked when `createBff` runs, so a configuration error stops the app at start-up.

## Routes

`fastifySession` adds three routes and reads the session in an `onRequest` hook on every other request:

| Route | What it does |
|---|---|
| `GET /auth/login` | Starts sign-in. Optional query parameters: `returnTo` (where the user lands) and `organization` (sign in to an organization). |
| `GET /auth/callback` | Finishes sign-in and sets the session cookie. |
| `GET` or `POST /auth/logout` | Signs out at KeenAuth and returns to your app. |

Sign-in uses the authorization code flow with PKCE (S256). The request is pushed to the server (PAR) when your environment offers it. On the callback the SDK checks `state`, `iss` and the ID token, including its `nonce`. Each successful sign-in creates a new session; the old one is discarded.

`returnTo` must be a path of your own app, such as `/orders?tab=open`. Any other value, such as `//evil.example` or a full URL, is ignored and the user lands on `/`.

## Protect routes

`fastifyRequireAuth(bff)` is a `preHandler` that lets a request through only with a session:

- a page request (`GET` or `HEAD`) without a session is redirected to `/auth/login` with `returnTo`;
- a request to `/api/…`, or with another method, gets `401` with a problem document. Pass `{ api: true }` to answer `401` on any path.

For `POST`, `PUT`, `PATCH`, `DELETE` and other unsafe methods, the browser must say the request comes from your app: `Sec-Fetch-Site: same-origin`, or an `Origin` header equal to your app's origin. Other requests get `403`. This protects against cross-site request forgery in addition to `SameSite=Lax`.

## Use the session and call your API

`request.keenauth` holds:

- `session`: `null`, or the signed-in user. `session.user` has typed ID token claims such as `subject`, `email`, `name`, `orgId` and `orgRoles`; all claims are in `session.user.claims`. The session object never contains a token.
- `accessToken`: a valid access token for server-side calls, or `null`.

```ts
app.get("/api/orders", { preHandler: fastifyRequireAuth(bff) }, async (request, reply) => {
  const upstream = await fetch("https://api.acme.example/v1/orders", {
    headers: { Authorization: `Bearer ${request.keenauth!.accessToken}` },
  });
  return reply.code(upstream.status).send(await upstream.json());
});
```

In TypeScript, declare the property once:

```ts
import type { SessionContext } from "@keenauth/node/bff";

declare module "fastify" {
  interface FastifyRequest {
    keenauth?: SessionContext | null;
  }
}
```

When the access token expires within 60 seconds, the SDK refreshes it before your handler runs. Each refresh rotates the refresh token and sets the new session cookie on the response. If the server refuses the refresh token, the session ends. A temporary server error keeps the session unchanged.

Do not send the access token to the browser.

## Switch organization

`bff.switchOrganizationPath("org_01j9…", "/dashboard")` returns a link to `/auth/login` that signs the user in again in that organization. KeenAuth checks the membership. After sign-in, `session.user.orgId` holds the organization.

## Sign out

Send a `POST` to `/auth/logout` from a form. The SDK:

1. deletes the session cookie (and the stored session, if you use a store);
2. revokes the refresh token;
3. sends the browser to your environment's logout endpoint, which returns it to your app.

A request that the browser marks as coming from another site is refused. Browsers that do not send `Sec-Fetch-Site` can sign out only with a `POST` from your own pages.

## Session storage

By default the whole session is in the cookie, encrypted and authenticated with AES-256-GCM using a key derived from `secret`. A changed or copied cookie is rejected. The cookie is named `__Host-keenauth_session.0` and set with `Secure`, `HttpOnly`, `SameSite=Lax` and `Path=/`. On `http://localhost` the `__Host-` prefix and `Secure` are left out. Large sessions are split into up to three cookies.

To keep tokens on the server, pass a store:

```ts
import { createBff, type SessionStore } from "@keenauth/node/bff";

const store: SessionStore = {
  get: async (id) => JSON.parse((await redis.get(`sess:${id}`)) ?? "null"),
  set: async (id, session, ttl) => void (await redis.set(`sess:${id}`, JSON.stringify(session), { EX: ttl })),
  delete: async (id) => void (await redis.del(`sess:${id}`)),
};
const bff = createBff({ /* … */ store });
```

The cookie then holds only an encrypted random session ID. Every sign-in creates a new ID and deletes the previous record. The store holds tokens, so restrict access to it. `MemorySessionStore` is for development and tests only.

A session lasts at most 7 days (`sessionMaxAge`); refreshing does not extend it. To change the secret, pass a list: `secret: [newSecret, oldSecret]`. Remove the old one after `sessionMaxAge`.

## Current limits

- DPoP-bound tokens and back-channel logout are not handled yet.
- Refreshes are shared only within one server process. With several instances, the application setting `refresh_reuse_interval_s` (default 5 seconds) lets a parallel refresh succeed; if you set it to `0`, the second refresh ends the session.