npm - @unidir/unidir-nextjs - Versions diffs - 1.0.0 - Mend

@unidir/unidir-nextjs 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,151 @@
+# @unidir/unidir-nextjs
+The official UniDir SDK for Next.js applications. This SDK provides secure, server-side OpenID Connect (OIDC) authentication using encrypted `httpOnly` cookies.
+## 🚀 Key Features
+- **Zero-Flicker Auth:** Validate sessions in Server Components before the page is sent to the browser.
+- **Encrypted Sessions:** Uses JWE (JSON Web Encryption) to ensure session data is unreadable and tamper-proof.
+- **App Router Optimized:** Built for Next.js 13, 14, and 15, including full support for Middleware and Server Actions.
+- **Secure by Default:** Tokens are exchanged on the server-side, keeping your `clientSecret` hidden from the browser.
+---
+## ⚙️ Installation
+Install the SDK and its core peer dependencies:
+```bash
+npm install @unidir/unidir-nextjs jose cookie
+```
+## 🛠️ Setup Guide
+### 1. Environment Variables
+Create a `.env.local` file in your project root.
+> **Note:** `UNIDIR_SECRET` must be a random string of at least 32 characters.
+```env
+UNIDIR_DOMAIN=[https://your-tenant.unidir.io](https://your-tenant.unidir.io)
+UNIDIR_CLIENT_ID=your_client_id
+UNIDIR_CLIENT_SECRET=your_client_secret
+UNIDIR_REDIRECT_URI=http://localhost:3000/api/auth/callback
+UNIDIR_SECRET='your_32_character_session_secret'
+```
+### 2. Initialize the SDK
+Create a shared library file to export your UniDir instance. This singleton will be used across your application.
+**lib/unidir.ts**
+````typescript
+import { initUniDir } from '@unidir/unidir-nextjs';
+export const unidir = initUniDir({
+  domain: process.env.UNIDIR_DOMAIN!,
+  clientId: process.env.UNIDIR_CLIENT_ID!,
+  clientSecret: process.env.UNIDIR_CLIENT_SECRET!,
+  secret: process.env.UNIDIR_SECRET!,
+  redirectUri: process.env.UNIDIR_REDIRECT_URI!,
+});
+### 3. API Route Handler
+Create a catch-all route to handle the authentication flow (login, logout, and callback).
+**app/api/auth/[unidir]/route.ts**
+```typescript
+import { unidir } from '@/lib/unidir';
+export const GET = unidir.handleAuth();
+````
+## 📖 Usage Gallery
+### Protecting Server Components (HOC)
+Use `withPageAuthRequired` to wrap pages that require authentication. It handles the redirect logic automatically.
+**app/dashboard/page.tsx**
+```tsx
+import { unidir } from "@/lib/unidir";
+async function Dashboard({ user }: { user: any }) {
+  return (
+    <div>
+      <h1>Protected Dashboard</h1>
+      <p>Welcome back, {user.name}!</p>
+    </div>
+  );
+}
+export default unidir.withPageAuthRequired(Dashboard);
+```
+### Accessing Auth State on the Client
+Wrap your root layout with the `UserProvider` and use the `useUser` hook in client components.
+**app/layout.tsx**
+```tsx
+import { UserProvider } from "@unidir/unidir-nextjs";
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <UserProvider>{children}</UserProvider>
+      </body>
+    </html>
+  );
+}
+```
+**components/UserMenu.tsx**
+```tsx
+"use client";
+import { useUser } from "@unidir/unidir-nextjs";
+export default function UserMenu() {
+  const { user, isLoading } = useUser();
+  if (isLoading) return <span>Loading...</span>;
+  return user ? (
+    <a href="/api/auth/logout">Logout</a>
+  ) : (
+    <a href="/api/auth/login">Login</a>
+  );
+}
+```
+🔒 Security Architecture
+httpOnly Cookies: Session tokens are stored in cookies that cannot be accessed via JavaScript (document.cookie), which prevents XSS-based token theft.
+Server-Side Exchange: The client_secret is used only on the server to exchange authorization codes for tokens.
+Tamper-Proof: Every session is signed and encrypted. If the UNIDIR_SECRET is compromised or the cookie is modified, the session becomes invalid.
+## 📄 API Reference
+| Method                       | Environment      | Description                                           |
+| :--------------------------- | :--------------- | :---------------------------------------------------- |
+| `handleAuth()`               | Server (API)     | Main router for `/login`, `/logout`, and `/callback`. |
+| `getSession(req)`            | Server (SSR/API) | Returns the decrypted user session.                   |
+| `withPageAuthRequired(Comp)` | Server (Page)    | HOC that redirects unauthenticated users.             |
+| `UserProvider`               | Client (Layout)  | Context provider for client-side state.               |
+| `useUser()`                  | Client (Hook)    | Access `{ user, isLoading, error }` in components.    |
+---
+## License
+MIT © UniDir

package/package.json ADDED Viewed

@@ -0,0 +1,38 @@
+{
+  "name": "@unidir/unidir-nextjs",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.tsx --format cjs,esm --dts --clean --minify --external react --external next",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --external react,next"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "next": "^16.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "cookie": "^1.1.1",
+    "jose": "^6.1.3"
+  }
+}

package/src/client.tsx ADDED Viewed

@@ -0,0 +1,101 @@
+"use client";
+import React, { createContext, useContext, useState, useEffect } from "react";
+import { UniDirConfig } from ".";
+import { verifyAccessToken } from "./jwks";
+import { JWTPayload } from "jose";
+const UserContext = createContext<{
+  user: any;
+  isLoading: boolean;
+  config: UniDirConfig | null;
+}>({ user: null, isLoading: true, config: null });
+export function UserProvider({
+  children,
+  config,
+}: {
+  children: React.ReactNode;
+  config: UniDirConfig;
+}) {
+  const [user, setUser] = useState<JWTPayload | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [token, setToken] = useState(null);
+  const [accessToken, setAccessToken] = useState(null);
+  const [refreshToken, setRefreshToken] = useState(null);
+  const [idToken, setIdToken] = useState(null);
+  const [client, setClient] = useState(null);
+  const [expiresIn, setExpiresIn] = useState(null);
+  //   useEffect(() => {
+  //     fetch("/api/auth/me")
+  //       .then((res) => res.json())
+  //       .then((data) => {
+  //         if (data) {
+  //           setUser(data.client);
+  //           setToken(data);
+  //           setAccessToken(data.access_token);
+  //           setRefreshToken(data.refresh_token);
+  //           const idTokenAll = await jwtVerify(
+  //             data.id_token,
+  //             config.jwks || "https://oauth.biocloud.pro/jwks.json"
+  //           );
+  //           setIdToken(data.id_token);
+  //           setClient(data.client);
+  //           setExpiresIn(data.expres_in);
+  //         }
+  //       })
+  //       .catch(() => setUser(null));
+  //   }, []);
+  useEffect(() => {
+    async function loadUser() {
+      try {
+        const res = await fetch("/api/auth/me");
+        const data = await res.json();
+        //setUser(data.user);
+        const { companyId, domainId, email, email_verified, name } =
+          await verifyAccessToken(
+            data.id_token,
+            config.jwks || "https://oauth.igoodworks.com/jwks.json",
+            {
+              issuer: config.issuer || "http://oauth.unidir.igoodworks.com/",
+              audience: config.clientId,
+            }
+          );
+        setUser({ companyId, domainId, email, email_verified, name });
+      } finally {
+        setIsLoading(false);
+      }
+    }
+    loadUser();
+  }, []);
+  return (
+    <UserContext.Provider
+      value={{
+        user,
+        isLoading,
+        config,
+        // token,
+        // expiresIn,
+        // accessToken,
+        // refreshToken,
+        // client,
+        // idToken,
+      }}
+    >
+      {children}
+    </UserContext.Provider>
+  );
+}
+export function getDeviceId(): string {
+  if (typeof window === "undefined") return "server-default";
+  let id = localStorage.getItem("unidir_device_id");
+  if (!id) {
+    id = crypto.randomUUID();
+    localStorage.setItem("unidir_device_id", id);
+  }
+  return id;
+}
+export const useUser = () => useContext(UserContext);

package/src/index.tsx ADDED Viewed

@@ -0,0 +1,198 @@
+import { parse } from "cookie";
+import { encrypt, decrypt } from "./session";
+import { NextRequest, NextResponse } from "next/server";
+import { redirect } from "next/navigation";
+import { generateCodeVerifier, generateCodeChallenge } from "./pkce";
+export interface UniDirConfig {
+  domain: string;
+  clientId: string;
+  clientSecret: string;
+  secret: string;
+  redirectUri: string;
+  logoutRedirectUri?: string;
+  deviceId?: string;
+  scope?: string;
+  audience?: string;
+  jwks?: string;
+  issuer?: string;
+}
+interface UniDirAction {
+  login: string;
+  loginPath: string;
+  logout: string;
+  callback: string;
+  me: string;
+}
+const defaultActions: UniDirAction = {
+  login: "login",
+  loginPath: "/api/auth/login",
+  logout: "logout",
+  callback: "callback",
+  me: "me",
+};
+export function initUniDir(config: UniDirConfig, actions?: UniDirAction) {
+  const uniDirActions = { ...defaultActions, ...actions };
+  const getSession = async (req: Request | NextRequest) => {
+    const cookieHeader = req.headers.get("cookie") || "";
+    const cookies = parse(cookieHeader);
+    const sessionToken = cookies["unidir_session"];
+    if (!sessionToken) return null;
+    return await decrypt(sessionToken, config.secret);
+  };
+  return {
+    handleAuth: () => async (req: NextRequest) => {
+      const action = req.nextUrl.pathname.split("/").pop();
+      // Capture the deviceId from the query param sent by the LoginButton
+      const queryDeviceId = req.nextUrl.searchParams.get("device_id");
+      const effectiveDeviceId =
+        queryDeviceId || config.deviceId || "unknown-device";
+      //const deviceId = req.headers.get("x-device-id");
+      if (action === uniDirActions.login) {
+        const returnTo = req.nextUrl.searchParams.get("returnTo") || "/";
+        const verifier = generateCodeVerifier();
+        const challenge = await generateCodeChallenge(verifier);
+        const url = new URL(`${config.domain}/authorize`);
+        url.searchParams.set("client_id", config.clientId);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("redirect_uri", config.redirectUri);
+        url.searchParams.set("scope", "openid profile email");
+        url.searchParams.set("code_challenge", challenge);
+        url.searchParams.set("code_challenge_method", "S256");
+        if (effectiveDeviceId) {
+          url.searchParams.set("device_id", effectiveDeviceId);
+        }
+        const response = NextResponse.redirect(url.toString());
+        // Store verifier in a short-lived, secure cookie
+        response.cookies.set("unidir_pkce_verifier", verifier, {
+          httpOnly: true,
+          secure: true,
+          sameSite: "lax",
+          maxAge: 60 * 5, // 5 minutes
+        });
+        response.cookies.set("unidir_device_id", effectiveDeviceId, {
+          httpOnly: true,
+          secure: true,
+          maxAge: 60 * 10, // 10 minutes
+        });
+        response.cookies.set("unidir_return_to", returnTo, {
+          httpOnly: true,
+          maxAge: 60 * 5,
+        });
+        return response;
+      }
+      // Profile Handler (for useUser hook)
+      if (action === uniDirActions.me) {
+        const session = await getSession(req);
+        if (!session)
+          return new NextResponse(JSON.stringify({ user: null }), {
+            status: 401,
+          });
+        return NextResponse.json(session);
+      }
+      // Logout Handler
+      if (action === uniDirActions.logout) {
+        const response = NextResponse.redirect(new URL("/", req.url));
+        response.cookies.delete("unidir_session");
+        return response;
+      }
+      if (action === "callback") {
+        const code = req.nextUrl.searchParams.get("code");
+        const verifier = req.cookies.get("unidir_pkce_verifier")?.value;
+        if (!code || !verifier) {
+          return new NextResponse("Missing code or verifier", { status: 400 });
+        }
+        const storedDeviceId = req.cookies.get("unidir_device_id")?.value;
+        const deviceIdToUse = storedDeviceId || effectiveDeviceId;
+        const res = await fetch(`${config.domain}/token`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-device-id": deviceIdToUse, // Added to header
+          },
+          body: JSON.stringify({
+            grant_type: "authorization_code",
+            client_id: config.clientId,
+            client_secret: config.clientSecret,
+            code,
+            code_verifier: verifier, // Pass the verifier back
+            redirect_uri: config.redirectUri,
+            device_id: deviceIdToUse,
+          }),
+        });
+        const tokens = await res.json();
+        if (tokens.error) return NextResponse.json(tokens, { status: 400 });
+        const encryptedSession = await encrypt(tokens, config.secret);
+        // const response = NextResponse.redirect(new URL("/", req.url));
+        const returnTo = req.cookies.get("unidir_return_to")?.value || "/";
+        const response = NextResponse.redirect(new URL(returnTo, req.url));
+        // Clean up PKCE cookie and set session
+        response.cookies.delete("unidir_pkce_verifier");
+        response.cookies.set("unidir_session", encryptedSession, {
+          httpOnly: true,
+          secure: true,
+          sameSite: "lax",
+          maxAge: 60 * 60 * 24,
+        });
+        return response;
+      }
+      return new NextResponse("Not Found", { status: 404 });
+    },
+    getSession,
+    withPageAuthRequired: <P extends object>(
+      Component: React.ComponentType<P>
+    ) => {
+      return async (props: P) => {
+        // Import headers dynamically to avoid issues in non-server environments
+        const { headers } = await import("next/headers");
+        const session = await getSession({ headers: await headers() } as any);
+        if (!session) {
+          redirect(uniDirActions.loginPath);
+        }
+        // Return the component as JSX
+        return <Component {...props} user={session} />;
+      };
+    },
+    withMiddlewareAuth: () => {
+      return async (req: NextRequest) => {
+        const sessionToken = req.cookies.get("unidir_session")?.value;
+        const session = sessionToken
+          ? await decrypt(sessionToken, config.secret)
+          : null;
+        if (!session) {
+          // Redirect to login but save the current URL to return back later
+          const { pathname, search } = req.nextUrl;
+          const url = new URL(uniDirActions.loginPath, req.url);
+          url.searchParams.set("returnTo", `${pathname}${search}`);
+          return NextResponse.redirect(url);
+        }
+        return NextResponse.next();
+      };
+    },
+  };
+}
+export { UserProvider, useUser } from "./client";

package/src/jwks.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import { jwtVerify, createRemoteJWKSet } from "jose";
+// Replace with your IdP issuer and audience
+const ISSUER = "https://YOUR_ISSUER/";
+const AUDIENCE = "YOUR_CLIENT_ID";
+export async function verifyAccessToken(
+  token: string,
+  jwksUrl: string,
+  options: Record<string, any> = {}
+) {
+  const JWKS = createRemoteJWKSet(new URL(jwksUrl));
+  const { payload } = await jwtVerify(token, JWKS, {
+    issuer: options.issuer,
+    audience: options.audience,
+  });
+  // Optionally apply custom claims checks here (e.g., roles, scopes)
+  return payload;
+}

package/src/pkce.ts ADDED Viewed

@@ -0,0 +1,18 @@
+export function generateCodeVerifier(): string {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return btoa(String.fromCharCode(...array))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+}
+export async function generateCodeChallenge(verifier: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return btoa(String.fromCharCode(...new Uint8Array(digest)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+}

package/src/session.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import { EncryptJWT, jwtDecrypt } from "jose";
+const getSecretKey = (secret: string) =>
+  new TextEncoder().encode(secret.padEnd(32, "0").slice(0, 32));
+export async function encrypt(payload: any, secret: string) {
+  return new EncryptJWT(payload)
+    .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
+    .setIssuedAt()
+    .setExpirationTime("24h")
+    .encrypt(getSecretKey(secret));
+}
+export async function decrypt(token: string, secret: string) {
+  try {
+    const { payload } = await jwtDecrypt(token, getSecretKey(secret));
+    return payload;
+  } catch (e) {
+    return null;
+  }
+}

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}