@tidecloak/nextjs 0.14.32-staging → 0.14.33

package/README.md

@@ -6,7 +6,7 @@ Add TideCloak authentication to your Next.js app.
 npm install @tidecloak/nextjs
 ```
 
-> New to TideCloak? Use our [Next.js template](../tidecloak-create-nextjs/README.md) to get started quickly.
+> New to TideCloak? Use our [Next.js template](https://github.com/tide-foundation/tidecloak-js/blob/main/packages/tidecloak-create-nextjs/README.md) to get started quickly.
 
 ---
 
@@ -27,13 +27,13 @@ npm install @tidecloak/nextjs
 | Best for | Simple apps | High-security apps |
 | Setup complexity | Easy | Medium |
 | Client-side token access | Yes | No |
-| Edge middleware | Yes | Yes |
+| Route protection (proxy/middleware) | Yes | Yes |
 
 ---
 
 ## Requirements
 
-- Next.js 13.4+ (App Router) or Next.js 12+ (Pages Router)
+- Next.js 13.5+ (App Router or Pages Router)
 - React 18+
 - A TideCloak server ([setup guide](https://github.com/tide-foundation/tidecloak-gettingstarted))
 - A registered client in your TideCloak realm
@@ -45,12 +45,12 @@ npm install @tidecloak/nextjs
 - `<TideCloakProvider>` - Application-level context
 - `useTideCloak()` - Hook for auth state and actions
 - `<Authenticated>` / `<Unauthenticated>` - UI guards
-- `createTideCloakMiddleware()` - Edge middleware for route protection
-- `createTideCloakProxy()` - Node.js proxy for route protection (recommended on Next.js 16+)
+- `createTideCloakProxy()` - Route protection in `proxy.ts` (Next.js 16+)
+- `createTideCloakMiddleware()` - Route protection in `middleware.ts` (Next.js 13.5 to 15)
 - `verifyTideCloakToken()` - Server-side JWT verification
 - `doEncrypt()` / `doDecrypt()` - Tag-based encryption
 
-> **DPoP is opt-in** (sender-constrained tokens). By default you get a plain, unbound access token. Pass `useDPoP: { mode: "auto" }` or `{ mode: "strict" }` in your provider config to turn it on — see the [`@tidecloak/js` DPoP docs](../tidecloak-js/docs/FRONT_CHANNEL.md#dpop-opt-in).
+> **DPoP is opt-in** (sender-constrained tokens). By default you get a plain, unbound access token. Pass `useDPoP: { mode: "auto" }` or `{ mode: "strict" }` in your provider config to turn it on. See the [`@tidecloak/js` DPoP docs](https://github.com/tide-foundation/tidecloak-js/blob/main/packages/tidecloak-js/docs/FRONT_CHANNEL.md#dpop-opt-in).
 
 ---
 

package/dist/types/server/tidecloakMiddleware.d.ts

@@ -15,11 +15,12 @@ interface JWK {
 export interface TidecloakConfig {
     realm: string;
     "auth-server-url": string;
-    "ssl-required": string;
-    resource: string;
-    "public-client": boolean;
-    "confidential-port": number;
-    jwk: {
+    "ssl-required"?: string;
+    resource?: string;
+    "public-client"?: boolean;
+    "confidential-port"?: number;
+    /** Local JWKS. When absent, keys are fetched from the realm's certs endpoint. */
+    jwk?: {
         keys: JWK[];
     };
     [key: string]: unknown;

package/dist/types/server/tidecloakMiddleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tidecloakMiddleware.d.ts","sourceRoot":"","sources":["../../../src/server/tidecloakMiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEvD,OAAO,EAEL,kBAAkB,EACnB,MAAM,iBAAiB,CAAA;AAExB,UAAU,GAAG;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE;QACH,IAAI,EAAE,GAAG,EAAE,CAAC;KACb,CAAC;IAEF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,MAAM,EAAE,eAAe,CAAA;IACvB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,kBAAkB,CAAA;IACpC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,CAAA;IACpF,kFAAkF;IAClF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,CAAA;IAC5F,0EAA0E;IAC1E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,CAAA;IACpF,wDAAwD;IACxD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,CAAA;CACvD;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,qBAAqB,SAM7B,WAAW,oCAwDlD"}
+{"version":3,"file":"tidecloakMiddleware.d.ts","sourceRoot":"","sources":["../../../src/server/tidecloakMiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEvD,OAAO,EAEL,kBAAkB,EACnB,MAAM,iBAAiB,CAAA;AAExB,UAAU,GAAG;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,GAAG,CAAC,EAAE;QACJ,IAAI,EAAE,GAAG,EAAE,CAAC;KACb,CAAC;IAEF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,MAAM,EAAE,eAAe,CAAA;IACvB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,kBAAkB,CAAA;IACpC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,CAAA;IACpF,kFAAkF;IAClF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,CAAA;IAC5F,0EAA0E;IAC1E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,CAAA;IACpF,wDAAwD;IACxD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,CAAA;CACvD;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,qBAAqB,SAM7B,WAAW,oCAwDlD"}

package/docs/FRONT_CHANNEL.md

@@ -0,0 +1,287 @@
+# Front-Channel Mode (Next.js)
+
+The default mode for Next.js apps. Your browser handles login and tokens directly.
+
+---
+
+## Setup
+
+### 1. Install
+
+```bash
+npm install @tidecloak/nextjs
+```
+
+### 2. Add Provider
+
+Download `tidecloak.json` (your client adapter config) from your TideCloak admin console and put it in your project root. `TideCloakProvider` takes its contents as `config`.
+
+**App Router:** `app/layout.tsx`
+
+```tsx
+import { TideCloakProvider } from '@tidecloak/nextjs';
+import adapter from '../tidecloak.json';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <TideCloakProvider config={adapter}>
+          {children}
+        </TideCloakProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+**Pages Router:** `pages/_app.tsx`
+
+```tsx
+import { TideCloakProvider } from '@tidecloak/nextjs';
+import adapter from '../tidecloak.json';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <TideCloakProvider config={adapter}>
+      <Component {...pageProps} />
+    </TideCloakProvider>
+  );
+}
+
+export default MyApp;
+```
+
+### 3. Create Redirect Page
+
+**App Router:** `app/auth/redirect/page.tsx`
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { useRouter } from 'next/navigation';
+import { useTideCloak } from '@tidecloak/nextjs';
+
+export default function RedirectPage() {
+  const { authenticated, isInitializing } = useTideCloak();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (!isInitializing) {
+      router.push(authenticated ? '/dashboard' : '/');
+    }
+  }, [authenticated, isInitializing, router]);
+
+  return <p>Loading...</p>;
+}
+```
+
+---
+
+## Using the Hook
+
+```tsx
+'use client';
+
+import { useTideCloak } from '@tidecloak/nextjs';
+
+export default function Header() {
+  const { authenticated, login, logout } = useTideCloak();
+
+  return (
+    <header>
+      {authenticated ? (
+        <button onClick={logout}>Log Out</button>
+      ) : (
+        <button onClick={login}>Log In</button>
+      )}
+    </header>
+  );
+}
+```
+
+---
+
+## Available Values
+
+```tsx
+const {
+  authenticated,        // true if logged in
+  isInitializing,       // true while SDK starts up
+  token,                // access token
+  tokenExp,             // token expiry timestamp
+  login,                // log in function
+  logout,               // log out function
+  refreshToken,         // refresh token function
+  getValueFromToken,    // get value from access token
+  getValueFromIdToken,  // get value from ID token
+  hasRealmRole,         // check realm role
+  hasClientRole,        // check client role
+  doEncrypt,            // encrypt data
+  doDecrypt,            // decrypt data
+} = useTideCloak();
+```
+
+---
+
+## Guard Components
+
+```tsx
+'use client';
+
+import { Authenticated, Unauthenticated } from '@tidecloak/nextjs';
+
+export default function Dashboard() {
+  return (
+    <>
+      <Authenticated>
+        <h1>Welcome to your dashboard!</h1>
+      </Authenticated>
+
+      <Unauthenticated>
+        <p>Please log in.</p>
+      </Unauthenticated>
+    </>
+  );
+}
+```
+
+---
+
+## Route Protection
+
+Protect routes with server-side auth checks.
+
+### Next.js 16+ (proxy.ts)
+
+Create `proxy.ts` at your project root:
+
+```ts
+import { NextResponse } from 'next/server';
+import tidecloakConfig from './tidecloak.json';
+import { createTideCloakProxy } from '@tidecloak/nextjs/server';
+
+export const proxy = createTideCloakProxy({
+  config: tidecloakConfig,
+  protectedRoutes: {
+    '/admin/*': ['admin'],
+    '/api/private/*': ['user'],
+  },
+  onFailure: ({ token }, req) => NextResponse.redirect(new URL('/login', req.url)),
+  onError: (err, req) => NextResponse.rewrite(new URL('/error', req.url)),
+});
+
+// Optional: limit which paths run the proxy
+export const config = {
+  matcher: ['/admin/:path*', '/api/private/:path*'],
+};
+```
+
+> `export const config = { matcher }` works in `proxy.ts`. Don't set `runtime` there: proxy always runs on the Node.js runtime.
+
+### Next.js 13.5 to 15 (middleware.ts)
+
+Create `middleware.ts` at your project root:
+
+```ts
+import { NextResponse } from 'next/server';
+import tidecloakConfig from './tidecloak.json';
+import { createTideCloakMiddleware } from '@tidecloak/nextjs/server';
+
+export default createTideCloakMiddleware({
+  config: tidecloakConfig,
+  protectedRoutes: {
+    '/admin/*': ['admin'],
+    '/api/private/*': ['user'],
+  },
+  onFailure: ({ token }, req) => NextResponse.redirect(new URL('/login', req.url)),
+  onError: (err, req) => NextResponse.rewrite(new URL('/error', req.url)),
+});
+
+export const config = {
+  matcher: [
+    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico)).*)',
+    '/api/(.*)',
+  ],
+};
+```
+
+### Options
+
+Both `createTideCloakProxy` and `createTideCloakMiddleware` accept the same options:
+
+| Option            | Type                                              | Description                                                                                  |
+| ----------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `config`          | `tidecloak.json` contents                         | Your TideCloak client adapter config.                                                        |
+| `protectedRoutes` | `Record<string, string[]>`                        | Map of route pattern → allowed roles (see pattern rules below).                              |
+| `cookieName`      | `string` (default `"kcToken"`)                    | Name of the cookie holding the access token.                                                 |
+| `onRequest`       | `(ctx, req) => NextResponse \| void`              | Runs before auth checks; return a response to short-circuit.                                 |
+| `onSuccess`       | `({ payload }, req) => NextResponse \| void`      | Runs after a token + role check passes.                                                       |
+| `onFailure`       | `({ token }, req) => NextResponse \| void`        | Runs when verification/role check fails. If omitted, responds `403`.                          |
+| `onError`         | `(err, req) => NextResponse`                      | Unexpected-error fallback. **Note the error is the first argument.** If omitted, the error is rethrown. |
+
+**`protectedRoutes` pattern rules:**
+
+- **Prefix**: `"/dashboard"` matches `/dashboard` and any sub-path.
+- **Glob**: `*` becomes a wildcard. A trailing `/*` also matches the bare base path, so `"/admin/*"` protects **both** `/admin` and `/admin/anything` (it will not match `/administrator`).
+- **`"OPTIONS"`**: matches requests by HTTP method instead of path.
+
+---
+
+## Server-Side Token Verification
+
+**App Router:** `app/api/secure/route.ts`
+
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
+import config from '../../../tidecloak.json';
+
+export async function GET(req: NextRequest) {
+  const token = req.cookies.get('kcToken')?.value || '';
+  const payload = await verifyTideCloakToken(config, token, ['user']);
+
+  if (!payload) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  return NextResponse.json({ data: 'Secure data' });
+}
+```
+
+---
+
+## Encrypting & Decrypting Data
+
+```tsx
+const { doEncrypt, doDecrypt } = useTideCloak();
+
+// Encrypt
+const [encrypted] = await doEncrypt([
+  { data: "sensitive info", tags: ["personal"] }
+]);
+
+// Decrypt
+const [decrypted] = await doDecrypt([
+  { encrypted, tags: ["personal"] }
+]);
+```
+
+### Data Types
+
+The `data` property **must** be either a string or a `Uint8Array` (raw bytes).
+
+```tsx
+// This will FAIL - objects not allowed
+await doEncrypt([{ data: { name: "John" }, tags: ["user"] }]);
+
+// This works - use strings
+await doEncrypt([{ data: JSON.stringify({ name: "John" }), tags: ["user"] }]);
+```
+
+### Permissions
+
+- Encryption requires `_tide_<tag>.selfencrypt` role
+- Decryption requires `_tide_<tag>.selfdecrypt` role
+- Users need roles matching **every** tag on a payload

package/docs/HYBRID_MODE.md

@@ -0,0 +1,387 @@
+# Hybrid/BFF Mode (Next.js)
+
+For Next.js apps that need extra security. Tokens stay on your server, not in the browser.
+
+Next.js is ideal for hybrid mode because you can use API routes to handle the token exchange.
+
+---
+
+## How It Works
+
+1. User clicks "Login"
+2. Browser redirects to TideCloak login page
+3. User logs in
+4. TideCloak redirects back with an authorization code
+5. Your **Next.js API route** exchanges the code for tokens
+6. API route creates a session (e.g., HTTP-only cookie)
+7. Tokens stay on your server, not in the browser
+
+---
+
+## When to Use This
+
+- Apps with sensitive data
+- When you don't want tokens in the browser
+- Apps that need server-side session control
+- When you want to use Next.js API routes for auth
+
+---
+
+## Setup
+
+### 1. Config
+
+Create your hybrid config:
+
+```ts
+// lib/tidecloakConfig.ts
+export const hybridConfig = {
+  authMode: "hybrid",
+  oidc: {
+    authorizationEndpoint: "https://auth.example.com/realms/myrealm/protocol/openid-connect/auth",
+    clientId: "my-app",
+    redirectUri: "https://myapp.com/auth/callback",
+    scope: "openid profile email"
+  },
+  tokenExchange: {
+    endpoint: "/api/auth/callback"  // Your Next.js API route
+  }
+};
+```
+
+### 2. Login Page
+
+**App Router:** `app/login/page.tsx`
+
+```tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { IAMService } from '@tidecloak/js';
+import { hybridConfig } from '@/lib/tidecloakConfig';
+
+export default function LoginPage() {
+  const [ready, setReady] = useState(false);
+  const searchParams = useSearchParams();
+  const returnUrl = searchParams.get('return') || '/dashboard';
+
+  useEffect(() => {
+    IAMService.loadConfig(hybridConfig).then(() => setReady(true));
+  }, []);
+
+  return (
+    <div>
+      <h1>Login</h1>
+      <button
+        disabled={!ready}
+        onClick={() => IAMService.doLogin(returnUrl)}
+      >
+        Login with TideCloak
+      </button>
+    </div>
+  );
+}
+```
+
+### 3. Callback Page
+
+**App Router:** `app/auth/callback/page.tsx`
+
+```tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { IAMService } from '@tidecloak/js';
+import { hybridConfig } from '@/lib/tidecloakConfig';
+
+export default function CallbackPage() {
+  const [error, setError] = useState<string | null>(null);
+  const router = useRouter();
+
+  useEffect(() => {
+    IAMService.initIAM(hybridConfig)
+      .then(authenticated => {
+        if (authenticated) {
+          const returnUrl = IAMService.getReturnUrl() || '/dashboard';
+          router.push(returnUrl);
+        } else {
+          setError('Login failed');
+        }
+      })
+      .catch(err => setError(err.message));
+  }, [router]);
+
+  if (error) {
+    return <div>Error: {error}</div>;
+  }
+
+  return <div>Logging in...</div>;
+}
+```
+
+### 4. API Route (Token Exchange)
+
+**App Router:** `app/api/auth/callback/route.ts`
+
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  exchangeCodeForTokens,
+  parseAuthCodeData,
+  setSessionCookie
+} from '@tidecloak/nextjs/server';
+import { createSession } from '@/lib/sessionStore';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const authData = parseAuthCodeData(body);
+
+  if (!authData) {
+    return NextResponse.json({ error: 'Invalid auth data' }, { status: 400 });
+  }
+
+  const result = await exchangeCodeForTokens({
+    authServerUrl: process.env.TIDECLOAK_URL!,
+    realm: process.env.TIDECLOAK_REALM!,
+    clientId: process.env.TIDECLOAK_CLIENT_ID!,
+  }, authData);
+
+  if (!result.success) {
+    return NextResponse.json({ error: result.error }, { status: 401 });
+  }
+
+  // Store tokens server-side and create session
+  const sessionId = createSession(result.tokens);
+
+  const response = NextResponse.json({ success: true });
+  setSessionCookie(response, sessionId, { maxAge: result.tokens.expires_in });
+
+  return response;
+}
+```
+
+---
+
+## Full Example with Session Management
+
+### Session Store
+
+```ts
+// lib/sessionStore.ts
+import type { TokenResponse } from '@tidecloak/nextjs/server';
+
+interface Session {
+  tokens: TokenResponse;
+  userId: string;
+}
+
+const sessions = new Map<string, Session>();
+
+export function createSession(tokens: TokenResponse): string {
+  const sessionId = crypto.randomUUID();
+  // Decode user ID from access token (it's a JWT)
+  const payload = JSON.parse(atob(tokens.access_token.split('.')[1]));
+  sessions.set(sessionId, { tokens, userId: payload.sub });
+  return sessionId;
+}
+
+export function getSession(sessionId: string): Session | undefined {
+  return sessions.get(sessionId);
+}
+
+export function updateSession(sessionId: string, tokens: TokenResponse): void {
+  const session = sessions.get(sessionId);
+  if (session) {
+    session.tokens = tokens;
+  }
+}
+
+export function deleteSession(sessionId: string): void {
+  sessions.delete(sessionId);
+}
+```
+
+### API Route with Session
+
+```ts
+// app/api/auth/callback/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  exchangeCodeForTokens,
+  parseAuthCodeData,
+  setSessionCookie
+} from '@tidecloak/nextjs/server';
+import { createSession } from '@/lib/sessionStore';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const authData = parseAuthCodeData(body);
+
+  if (!authData) {
+    return NextResponse.json({ error: 'Invalid auth data' }, { status: 400 });
+  }
+
+  const result = await exchangeCodeForTokens({
+    authServerUrl: process.env.TIDECLOAK_URL!,
+    realm: process.env.TIDECLOAK_REALM!,
+    clientId: process.env.TIDECLOAK_CLIENT_ID!,
+  }, authData);
+
+  if (!result.success) {
+    return NextResponse.json({ error: result.error }, { status: 401 });
+  }
+
+  const sessionId = createSession(result.tokens);
+
+  const response = NextResponse.json({ success: true });
+  setSessionCookie(response, sessionId, { maxAge: 60 * 60 * 24 });
+
+  return response;
+}
+```
+
+### Protected API Route
+
+```ts
+// app/api/user/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getSessionFromRequest } from '@tidecloak/nextjs/server';
+import { getSession } from '@/lib/sessionStore';
+
+export async function GET(req: NextRequest) {
+  const sessionId = getSessionFromRequest(req);
+
+  if (!sessionId) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const session = getSession(sessionId);
+  if (!session) {
+    return NextResponse.json({ error: 'Session expired' }, { status: 401 });
+  }
+
+  // Use server-side tokens for API calls
+  const userInfo = await fetch(
+    `${process.env.TIDECLOAK_URL}/realms/${process.env.TIDECLOAK_REALM}/protocol/openid-connect/userinfo`,
+    {
+      headers: { Authorization: `Bearer ${session.tokens.access_token}` },
+    }
+  );
+
+  return NextResponse.json(await userInfo.json());
+}
+```
+
+### Token Refresh
+
+```ts
+// app/api/auth/refresh/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  refreshAccessToken,
+  getSessionFromRequest,
+  setSessionCookie
+} from '@tidecloak/nextjs/server';
+import { getSession, updateSession } from '@/lib/sessionStore';
+
+export async function POST(req: NextRequest) {
+  const sessionId = getSessionFromRequest(req);
+
+  if (!sessionId) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const session = getSession(sessionId);
+  if (!session?.tokens.refresh_token) {
+    return NextResponse.json({ error: 'No refresh token' }, { status: 401 });
+  }
+
+  const result = await refreshAccessToken({
+    authServerUrl: process.env.TIDECLOAK_URL!,
+    realm: process.env.TIDECLOAK_REALM!,
+    clientId: process.env.TIDECLOAK_CLIENT_ID!,
+  }, session.tokens.refresh_token);
+
+  if (!result.success) {
+    return NextResponse.json({ error: result.error }, { status: 401 });
+  }
+
+  updateSession(sessionId, result.tokens);
+
+  const response = NextResponse.json({ success: true });
+  setSessionCookie(response, sessionId, { maxAge: result.tokens.expires_in });
+
+  return response;
+}
+```
+
+### Logout
+
+```ts
+// app/api/auth/logout/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getSessionFromRequest, clearSessionCookie } from '@tidecloak/nextjs/server';
+import { deleteSession } from '@/lib/sessionStore';
+
+export async function POST(req: NextRequest) {
+  const sessionId = getSessionFromRequest(req);
+
+  if (sessionId) {
+    deleteSession(sessionId);
+  }
+
+  const response = NextResponse.json({ success: true });
+  clearSessionCookie(response);
+
+  return response;
+}
+```
+
+---
+
+## Limitations
+
+In hybrid mode, tokens are on your server, so these client-side methods won't work:
+
+- `getToken()`, `getIDToken()`
+- `getName()`, `hasRealmRole()`, `hasClientRole()`
+- `getValueFromToken()`, `getValueFromIDToken()`
+- `doEncrypt()`, `doDecrypt()`
+
+Use these instead:
+- `isLoggedIn()` - Check if user completed login flow
+- `getReturnUrl()` - Get the page user wanted to visit
+
+Your API routes should provide user info to the client.
+
+---
+
+## Server Utilities
+
+Import from `@tidecloak/nextjs/server`:
+
+| Function | Description |
+|----------|-------------|
+| `exchangeCodeForTokens(config, authData)` | Exchange authorization code for tokens |
+| `refreshAccessToken(config, refreshToken)` | Refresh an expired access token |
+| `parseAuthCodeData(body)` | Parse auth code data from request body |
+| `setSessionCookie(response, sessionId, options?)` | Set HTTP-only session cookie |
+| `getSessionFromRequest(req, cookieName?)` | Get session ID from request cookies |
+| `clearSessionCookie(response, cookieName?)` | Clear session cookie |
+| `verifyTideCloakToken(config, token, roles?)` | Verify JWT and check roles |
+| `createTideCloakProxy(options)` | Create proxy for route protection (Next.js 16+) |
+| `createTideCloakMiddleware(options)` | Create middleware for route protection (Next.js 13.5 to 15) |
+
+---
+
+## When to Use Hybrid vs Front-channel
+
+| Scenario | Mode |
+|----------|------|
+| Need tokens in browser for client-side API calls | Front-channel |
+| Tokens should never be in browser | Hybrid |
+| Server needs to make API calls on behalf of user | Hybrid |
+| Simple SPA with public API | Front-channel |
+| Sensitive data, high security requirements | Hybrid |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidecloak/nextjs",
-  "version": "0.14.32-staging",
+  "version": "0.14.33",
   "description": "TideCloak nextjs SDK",
   "exports": {
     ".": {
@@ -18,7 +18,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"
@@ -52,8 +53,8 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@tidecloak/react": "0.14.32-staging",
-    "@tidecloak/verify": "0.14.32-staging"
+    "@tidecloak/react": "^0.14.33",
+    "@tidecloak/verify": "^0.14.33"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",