@tidecloak/nextjs 0.9.11 → 0.9.13

package/README.md

@@ -1,24 +1,38 @@
 # TideCloak NextJS SDK
 
-Secure your Next.js app with TideCloak: authentication, session management, data encryption, and edge-middleware integration-all in minutes.
+> ## Quick Start Template
+>
+> If you're new to TideCloak, the fastest way to get started is with our official Next.js template:  
+> [`@tidecloak/create-nextjs`](../tidecloak-create-nextjs/README.md)  
+> It scaffolds a working project with authentication, middleware, and optional IAM setup — so you can start building right away.
+>
+>---
+
+
+Secure your Next.js app with TideCloak: authentication, session management, data encryption, and edge-middleware integration.
 
 ---
 
 ## 1. Prerequisites
 
-Before you begin, ensure you have:
+Before you begin, ensure you have the following:
 
-* Next.js 13.5.7 or later
-* React 18 or later
-* Node.js ≥18.17.0
-* A running TideCloak server
-* A registered client in your realm
+* **Next.js**:
 
----
+  * App Router (recommended): Next.js 13.4 or later (for `layout.tsx` support)
+  * Pages Router (legacy): Next.js 12 or later (for `_app.tsx` support)
+* **React 18** or later
+* **Node.js ≥18.17.0**
+* A [running](https://github.com/tide-foundation/tidecloak-gettingstarted) TideCloak server you have admin control over.
+* IGA enabled realm
+* A registered client in your realm with default user contexts approved and committed
+* A valid Keycloak adapter JSON file (e.g., `tidecloakAdapter.json`)
 
-## 2. Install the SDK
+> Note: Choose either the App Router or the Pages Router for your project. You only need one routing system active.
 
-Add the NextJS bundle to your project:
+## 2. Install `@tidecloak/nextjs`
+
+Add `@tidecloak/nextjs` to your project:
 
 ```bash
 npm install @tidecloak/nextjs
@@ -28,51 +42,153 @@ yarn add @tidecloak/nextjs
 
 This bundle provides:
 
-* `<TideCloakProvider>` - application-level context
-* `useTideCloak()` hook - access tokens and auth actions
-* `verifyTideCloakToken()` - server-side JWT verification
-* `<Authenticated>` / `<Unauthenticated>` - UI guards
-* `doEncrypt()` / `doDecrypt()` - tag-based encryption/decryption
-* `createTideCloakMiddleware()` - Edge middleware for route protection (supports both Pages & App routers)
+* `<TideCloakProvider>` — application-level context
+* `useTideCloak()` hook — access tokens and auth actions
+* `verifyTideCloakToken()` — server-side JWT verification
+* `<Authenticated>` / `<Unauthenticated>` — UI guards
+* `doEncrypt()` / `doDecrypt()` — tag-based encryption/decryption
+* `createTideCloakMiddleware()` — Edge middleware for route protection (supports both Pages & App routers)
 
 ---
 
 ## 3. Initialize the Provider
 
-Wrap your root component in `<TideCloakProvider>` to load adapter settings and bootstrap auth:
+To begin using the SDK, wrap your application with `<TideCloakProvider>`.
+
+This makes authentication state, token access, and authorization tools available throughout your app. You only need to wrap once—at the top level entry point depending on which routing system you're using.
+
+---
+
+### App Router
+
+**File:** `/app/layout.tsx`
 
 ```tsx
-'use client'
 import React from 'react';
 import { TideCloakProvider } from '@tidecloak/nextjs';
 import adapter from '../tidecloakAdapter.json';
 
-export default function App() {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <TideCloakProvider config={{ ...adapter }}>
+          {children}
+        </TideCloakProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+**Description:** This `layout.tsx` is used by Next.js’s App Router. It defines the root HTML structure and wraps all nested pages and layouts with `TideCloakProvider`, making authentication context available everywhere in the `/app` directory.
+
+---
+
+### Pages Router
+
+**File:** `/pages/_app.tsx`
+
+```tsx
+import React from 'react';
+import { TideCloakProvider } from '@tidecloak/nextjs';
+import adapter from '../tidecloakAdapter.json';
+
+function MyApp({ Component, pageProps }) {
   return (
     <TideCloakProvider config={adapter}>
-      <YourApp />
+      <Component {...pageProps} />
     </TideCloakProvider>
   );
 }
+
+export default MyApp;
+```
+
+**Description:** The `_app.tsx` file is the entry point for the Pages Router. It wraps every page component in the `/pages` directory with `TideCloakProvider`, so that authentication state and methods are accessible across all your pages.
+
+---
+
+## 4. Redirect URI Handling
+
+TideCloak supports an optional `redirectUri` parameter. This is the URL users are sent to after login or logout.
+
+If omitted, it defaults to:
+
+```ts
+`${window.location.origin}/auth/redirect`
 ```
 
-**What it does:**
+> If your app runs at `http://localhost:3000`, then by default users will be redirected to `http://localhost:3000/auth/redirect` after login or logout.
+>
+> If that route doesn't exist in your project, you must create it or explicitly define a different `redirectUri` in your TideCloak config.
+
+If you use the default, you **must create a page** at `/auth/redirect` in your app.
+
+You can customize this URI in your provider config:
+
+```tsx
+<TideCloakProvider config={{ ...adapter, redirectUri: 'https://yourapp.com/auth/callback' }}>
+  {children}
+</TideCloakProvider>
+```
+
+### Example: `/app/auth/redirect/page.tsx`
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { useRouter } from 'next/navigation';
+import { useTideCloak } from '@tidecloak/nextjs';
 
-* **Loads** your adapter JSON
-* **Initializes** internal auth flows and listeners
-* **Provides** auth state & methods via React Context
+export default function RedirectPage() {
+  const { authenticated, isInitializing, logout } = useTideCloak();
+  const router = useRouter();
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    if (params.get("auth") === "failed") {
+      sessionStorage.setItem("tokenExpired", "true");
+      logout();
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!isInitializing) {
+      router.push(authenticated ? '/home' : '/');
+    }
+  }, [authenticated, isInitializing, router]);
+
+  return (
+    <div style={{
+      minHeight: '100vh',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      fontSize: '1rem',
+      color: '#555',
+    }}>
+      <p>Waiting for authentication...</p>
+    </div>
+  );
+}
+```
+
+This page helps finalize the login or logout flow, and also reacts to token expiration events that may have triggered a redirect from the middleware.
 
 ---
 
 ## 4. Using the `useTideCloak` Hook
 
-Use this hook anywhere to manage auth:
+Use this hook anywhere in your React component tree to manage authentication:
 
 ```tsx
 'use client'
+import React from 'react';
 import { useTideCloak } from '@tidecloak/nextjs';
 
-function Header() {
+export default function Header() {
   const {
     authenticated,
     login,
@@ -111,7 +227,7 @@ function Header() {
 | `authenticated`                       | `boolean`                                    | Whether the user is logged in.                                          |
 | `login()` / `logout()`                | `() => void`                                 | Trigger the login or logout flows.                                      |
 | `token`, `tokenExp`                   | `string`, `number`                           | Access token and its expiration timestamp.                              |
-| Automatic token refresh               | built-in                                     | Tokens refresh silently on expiration-no manual setup needed.           |
+| Automatic token refresh               | built-in                                     | Tokens refresh silently on expiration—no manual setup needed.           |
 | `refreshToken()`                      | `() => Promise<boolean>`                     | Force a silent token renewal.                                           |
 | `getValueFromToken(key)`              | `(key: string) => any`                       | Read a custom claim from the access token.                              |
 | `getValueFromIdToken(key)`            | `(key: string) => any`                       | Read a custom claim from the ID token.                                  |
@@ -123,18 +239,19 @@ function Header() {
 
 ## 5. Guard Components
 
-Use out-of-the-box components to show or hide content:
+Use these components to conditionally render UI based on auth state:
 
 ```tsx
 'use client'
+import React from 'react';
 import { Authenticated, Unauthenticated } from '@tidecloak/nextjs';
 
-function Dashboard() {
+export default function Dashboard() {
   return (
     <>
       <Authenticated>
         <h1>Dashboard</h1>
-        {/* Protected widgets */}
+        {/* Protected widgets here */}
       </Authenticated>
 
       <Unauthenticated>
@@ -152,65 +269,38 @@ function Dashboard() {
 
 ## 6. Encrypting & Decrypting Data
 
-TideCloak lets you protect sensitive fields with **tag-based** encryption. Pass in an array of `{ data, tags }` objects and receive encrypted strings (or vice versa).
-
-### Syntax Overview
+Protect sensitive payloads using tag-based encryption/decryption:
 
 ```ts
 // Encrypt payloads:
 const encryptedArray = await doEncrypt([
-  { data: /* any JSON-serializable value */, tags: ['tag1', 'tag2'] },
-  // …
+  { data: { email: 'user@example.com' }, tags: ['email'] },
 ]);
 
 // Decrypt blobs:
 const decryptedArray = await doDecrypt([
-  { encrypted: /* string from encrypt() */, tags: ['tag1', 'tag2'] },
-  // …
+  { encrypted: encryptedArray[0], tags: ['email'] },
 ]);
 ```
 
-> **Order guarantee**: the returned array matches the input order.
-
-### Permissions
-
-* **Encryption** requires roles `tide_<tag>.selfencrypt` for each tag.
-* **Decryption** requires roles `tide_<tag>.selfdecrypt` for each tag.
+* **Permissions**: Encryption requires roles `tide_<tag>.selfencrypt`; decryption requires `tide_<tag>.selfdecrypt`.
+* **Order guarantee**: Output array preserves input order.
 
 ---
 
 ## 7. Edge Middleware with TideCloak
 
-TideCloak’s Edge middleware works seamlessly with both the **Pages Router** and the **App Router** in Next.js:
-
-* **Pages Router**: Place your `middleware.ts` file at the project root alongside `pages/`. The exported middleware will apply to both page and API routes.
-* **App Router**: Put `middleware.ts` at the project root (or inside `src/`). It integrates with `/app` routes and layouts, protecting both server components and route handlers.
-
-### 7.1 Installation
-
-No additional install-middleware is included in `@tidecloak/nextjs`.
-
-### 7.2 Options
+Place your middleware at the project root for both routers.
 
-* **`config`** (`TidecloakConfig`): Your Keycloak adapter JSON (downloaded from your TideCloak client settings).
-* **`publicRoutes`** (`RoutePattern[]`): Paths to bypass authentication (strings/globs/regex/functions).
-* **`protectedRoutes`** (`ProtectedRoutesMap`): Map of path patterns to arrays of required roles.
-* **`onRequest`**<br>`(ctx: { token: string | null }, req: NextRequest) => NextResponse | void`<br>Hook before auth logic; can short-circuit by returning a `NextResponse`.
-* **`onSuccess`**<br>`(ctx: { payload: Record<string, any> }, req: NextRequest) => NextResponse | void`<br>Hook after successful auth & role checks; override the response by returning one.
-* **`onFailure`**<br>`(ctx: { token: string | null }, req: NextRequest) => NextResponse | void`<br>Hook when auth or role check fails; return a `NextResponse` to override.
-* **`onError`**<br>`(err: any, req: NextRequest) => NextResponse`<br>Hook for unexpected errors in middleware logic.
-
-### 7.3 Example Usage
-
-Place the following `middleware.ts` at your project root (works for both Pages and App routers) to protect both page routes and API handlers:
+**File:** `/middleware.ts`
 
 ```ts
 import { NextResponse } from 'next/server';
-import keycloakConfig from './tidecloak.config.json';
+import config from './tidecloak.config.json';
 import { createTideCloakMiddleware } from '@tidecloak/nextjs/server/tidecloakMiddleware';
 
 export default createTideCloakMiddleware({
-  config: keycloakConfig,
+  config,
   publicRoutes: ['/', '/about'],
   protectedRoutes: {
     '/admin/*': ['admin'],
@@ -222,122 +312,63 @@ export default createTideCloakMiddleware({
 
 export const config = {
   matcher: [
-    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico)).*)',
+    '/((?!_next|[^?]*\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico)).*)',
     '/api/(.*)',
   ],
   runtime: 'edge',
 };
 ```
 
-**Flow:**
-
-1. Bypass any `publicRoutes`
-2. Read the `kcToken` cookie
-3. Invoke `onRequest` hook (if provided)
-4. Match path against `protectedRoutes` patterns
-5. Verify signature, issuer, and roles via `verifyTideCloakToken()`
-6. On success: `onSuccess` hook or `NextResponse.next()`
-7. On failure: `onFailure` hook or default 403 response
-8. On unexpected errors: `onError` hook
+**Description:** The `middleware.ts` file runs at the Edge runtime before any page or API request. It applies authentication and role-based access control globally, using your adapter settings to verify tokens and redirect or rewrite responses as needed.
 
 ---
 
-### 7.4. Server‑Side Token Verification
-
-You can verify TideCloak-issued JWTs on your server or API routes using `verifyTideCloakToken`:
-
-```ts
-import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
-
-// Returns the decoded payload if valid and roles pass, otherwise null
-const payload = await verifyTideCloakToken(
-  config,       // Your TideCloak adapter JSON
-  token,        // Raw access token to verify
-  ['admin', 'user'] // Optional roles; user must have at least one
-);
-
-if (!payload) {
-  // Invalid token or insufficient roles
-}
-```
-
-Under the hood, it uses `jose` for cryptographic verification and key management:
-
-```ts
-import { jwtVerify, createLocalJWKSet, createRemoteJWKSet } from 'jose';
-
-export async function verifyTideCloakToken(config, token, allowedRoles = []) {
-  // Implementation checks token presence, issuer, signature,
-  // authorized party (azp), and at least one allowed role.
-}
-```
-
-**Parameters:**
-
-* `config` (`object`): Your TideCloak adapter JSON (parsed Keycloak config).
-* `token` (`string`): Access token string to verify.
-* `allowedRoles` (`string[]`, optional): Array of realm or client roles; user must have at least one.
-
-**Returns:**
-
-* `Promise<object | null>`: Decoded JWT payload if valid and role check passes; otherwise `null`.
-
-### Example: Protecting an API Route
+## 8. Server‑Side Token Verification
 
-Protect your server-side endpoints by verifying the JWT before proceeding.
+### Pages Router
 
-#### Pages Router
+**File:** `/pages/api/secure.ts`
 
 ```ts
-// pages/api/secure.ts
 import type { NextApiRequest, NextApiResponse } from 'next';
 import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
 import config from '../../tidecloakAdapter.json';
 
 export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  // Extract token from cookie or Authorization header
   const token = req.cookies.kcToken || req.headers.authorization?.split(' ')[1] || '';
-
-  // Verify signature, issuer, and roles (e.g., 'user')
   const payload = await verifyTideCloakToken(config, token, ['user']);
   if (!payload) {
     return res.status(401).json({ error: 'Unauthorized' });
   }
-
-  // Proceed with secure logic
   res.status(200).json({ data: 'Secure data response' });
 }
 ```
 
-#### App Router
+### App Router
+
+**File:** `/app/api/secure/route.ts`
 
 ```ts
-// app/api/secure/route.ts
 import { NextRequest, NextResponse } from 'next/server';
 import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
 import config from '../../../tidecloakAdapter.json';
 
 export async function GET(req: NextRequest) {
-  // Extract token from cookie
   const token = req.cookies.get('kcToken')?.value || '';
-
-  // Verify signature, issuer, and roles (e.g., 'user')
   const payload = await verifyTideCloakToken(config, token, ['user']);
   if (!payload) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
   }
-
-  // Proceed with secure logic
   return NextResponse.json({ data: 'Secure data response' });
 }
 ```
 
 ---
 
-## 8. Advanced & Best Practices
+## 9. Advanced & Best Practices
 
-* **Auto-Refresh**: built into the provider-no manual timers.
-* **Error Handling**: use the `initError` value from `useTideCloak`.
+* **Auto-Refresh**: built into the provider—no manual timers.
+* **Error Handling**: use the `initError` property from `useTideCloak`.
 * **Custom Claims**: read via `getValueFromToken()` / `getValueFromIdToken()`.
 * **Role-Based UI**: combine hooks & guard components for fine-grained control.
 * **Lazy Initialization**: wrap `<TideCloakProvider>` around only protected sections in large apps.

package/dist/cjs/contexts/InternalTideCloakProvider.js

@@ -0,0 +1,4 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TideCloakContextProvider } from "@tidecloak/react";
+export const InternalTideCloakProvider = ({ config, children }) => (_jsx(TideCloakContextProvider, { config: config, children: children }));

package/dist/cjs/contexts/TideCloakProvider.js

@@ -0,0 +1,4 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { InternalTideCloakProvider } from "./InternalTideCloakProvider";
+export const TideCloakProvider = ({ config, children }) => (_jsx(InternalTideCloakProvider, { config: config, children: children }));

package/dist/cjs/index.js

@@ -1 +1,4 @@
-export * from '@tidecloak/react';
+'use client';
+import { useTideCloak, Authenticated, Unauthenticated, TideCloakContextProvider } from '@tidecloak/react';
+export { useTideCloak, Authenticated, Unauthenticated, TideCloakContextProvider };
+export { TideCloakProvider } from "./contexts/TideCloakProvider";

package/dist/esm/contexts/InternalTideCloakProvider.js

@@ -0,0 +1,4 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TideCloakContextProvider } from "@tidecloak/react";
+export const InternalTideCloakProvider = ({ config, children }) => (_jsx(TideCloakContextProvider, { config: config, children: children }));

package/dist/esm/contexts/TideCloakProvider.js

@@ -0,0 +1,4 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { InternalTideCloakProvider } from "./InternalTideCloakProvider";
+export const TideCloakProvider = ({ config, children }) => (_jsx(InternalTideCloakProvider, { config: config, children: children }));

package/dist/esm/index.js

@@ -1 +1,4 @@
-export * from '@tidecloak/react';
+'use client';
+import { useTideCloak, Authenticated, Unauthenticated, TideCloakContextProvider } from '@tidecloak/react';
+export { useTideCloak, Authenticated, Unauthenticated, TideCloakContextProvider };
+export { TideCloakProvider } from "./contexts/TideCloakProvider";

package/dist/types/contexts/InternalTideCloakProvider.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode, FC } from "react";
+export interface TideCloakProviderProps {
+    config: Record<string, any>;
+    children: ReactNode;
+}
+export declare const InternalTideCloakProvider: FC<TideCloakProviderProps>;
+//# sourceMappingURL=InternalTideCloakProvider.d.ts.map

package/dist/types/contexts/InternalTideCloakProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InternalTideCloakProvider.d.ts","sourceRoot":"","sources":["../../../src/contexts/InternalTideCloakProvider.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAGtC,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,eAAO,MAAM,yBAAyB,EAAG,EAAE,CAAC,sBAAsB,CAIjE,CAAC"}

package/dist/types/contexts/TideCloakProvider.d.ts

@@ -0,0 +1,4 @@
+import { FC } from "react";
+import { TideCloakProviderProps } from "./InternalTideCloakProvider";
+export declare const TideCloakProvider: FC<TideCloakProviderProps>;
+//# sourceMappingURL=TideCloakProvider.d.ts.map

package/dist/types/contexts/TideCloakProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TideCloakProvider.d.ts","sourceRoot":"","sources":["../../../src/contexts/TideCloakProvider.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAC3B,OAAO,EAA6B,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGhG,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAAC,sBAAsB,CAIxD,CAAC"}

package/dist/types/index.d.ts

@@ -1,2 +1,4 @@
-export * from '@tidecloak/react';
+import { useTideCloak, Authenticated, Unauthenticated, TideCloakContextProvider } from '@tidecloak/react';
+export { useTideCloak, Authenticated, Unauthenticated, TideCloakContextProvider };
+export { TideCloakProvider } from "./contexts/TideCloakProvider";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,eAAe,EACf,wBAAwB,EACzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,YAAY,EACZ,aAAa,EACb,eAAe,EACf,wBAAwB,EACzB,CAAC;AACF,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidecloak/nextjs",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "TideCloak nextjs SDK",
   "exports": {
     ".": {
@@ -34,7 +34,8 @@
     "oidc",
     "oauth2",
     "authorization",
-    "react"
+    "react",
+    "nextjs"
   ],
   "peerDependencies": {
     "next": ">=13",
@@ -47,8 +48,8 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@tidecloak/react": "^0.9.11",
-    "@tidecloak/verify": "^0.9.12"
+    "@tidecloak/react": "^0.9.13",
+    "@tidecloak/verify": "^0.9.13"
   },
   "devDependencies": {
     "@types/react": "^19.1.8",