feat(auth): handle refresh token (#67)

* feat: handle refresh token

* refactor: move to constants file

* refactor: env var

* refactor: use NEXT_PUBLIC_OIDC_PROVIDER_ID as unique env var

* refactor: update doc for env vars

* lint and format

* feat: configure hey-api client passing the bearer token to api services

* feat(auth): handle refresh token

* refactor: refresh token diagram flow

* fix: remove leftover catalogue page

* fix: api-client new instance

* fix: raise console error in case of missing token or userId

* fix: redirect to sign in if refresh token is expired

* feat: implement OIDC authentication with automatic token refresh

- Add Better Auth with OIDC (OAuth2 Authorization Code Flow)
- Implement custom token storage in encrypted HTTP-only cookies
- Add automatic access token refresh when expired
- Create dedicated /api/auth/refresh-token endpoint
- Fix race condition by creating new client instance per request
- Add fail-fast validation for API_BASE_URL env var
- Add refresh token expiration check before API call
- Add warning when provider doesn't return new refresh token
- Add account.update.after hook for re-login flow
- Add comprehensive auth documentation in src/lib/auth/README.md
- Add 22 unit tests for auth flows

Security improvements:
- AES-256-GCM encryption for token storage
- Server-side only API client (no token exposure to client)
- HTTP-only cookies (not accessible via JavaScript)
- SameSite protection
- 7-day session management with Better Auth cookie cache

Fixes #50

* refactor: move to util reusable account auth info

* fix: update env var

* fix: remove throw error on better auth secret env var

* fix: remove throw error on api base url env var

* refactor: comment

* fix: types

* leftover

* feat(card): add server card component

* fix: client api on server actions

* chore: pnpm script for run real oidc + msw

* fix: redirect issue

* format

* test: update use cases

Author: peppescg

AGENTS.md

@@ -276,7 +276,8 @@ export async function createServer(formData: FormData) {
 ### Using Generated API Client
 
 **⚠️ IMPORTANT:**
-- Never edit files in `src/generated/*`** - they are auto-generated and will be overwritten
+
+- Never edit files in `src/generated/*`\*\* - they are auto-generated and will be overwritten
 - **Always use server actions** - Client components should not call the API directly
 - The API client is server-side only (no `NEXT_PUBLIC_` env vars needed)
 
@@ -325,7 +326,13 @@ pnpm generate-client  # Fetch swagger.json and regenerate
 
 - OIDC provider agnostic
 - Stateless JWT authentication
-- Environment variables: `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`
+- Environment variables:
+  - `OIDC_ISSUER_URL` - OIDC provider URL
+  - `OIDC_CLIENT_ID` - OAuth2 client ID
+  - `OIDC_CLIENT_SECRET` - OAuth2 client secret
+  - `NEXT_PUBLIC_OIDC_PROVIDER_ID` - Provider identifier (e.g., "okta", "oidc") - **Required**, must use `NEXT_PUBLIC_` prefix. Not sensitive data - it's just an identifier.
+  - `BETTER_AUTH_URL` - Application base URL
+  - `BETTER_AUTH_SECRET` - Secret for token encryption
 
 ### Development
 

CLAUDE.md

@@ -205,6 +205,7 @@ pnpm generate-client:nofetch # Regenerate without fetching
 ### Mocking & Testing
 
 - **MSW Auto-Mocker**
+
   - Auto-generates handlers from `swagger.json` and creates fixtures under `src/mocks/fixtures` on first run.
   - Strict validation with Ajv + ajv-formats; fixtures are type-checked against `@api/types.gen` by default.
   - Hand-written, non-schema mocks live in `src/mocks/customHandlers` and take precedence over schema-based mocks.
@@ -274,7 +275,13 @@ git push origin v0.x.x
 ### Authentication Not Working
 
 - **Development**: Ensure OIDC mock is running (`pnpm oidc`)
-- **Production**: Check environment variables (OIDC_ISSUER, CLIENT_ID, etc.)
+- **Production**: Check environment variables:
+  - `OIDC_ISSUER_URL` - OIDC provider URL
+  - `OIDC_CLIENT_ID` - OAuth2 client ID
+  - `OIDC_CLIENT_SECRET` - OAuth2 client secret
+  - `NEXT_PUBLIC_OIDC_PROVIDER_ID` - Provider identifier (e.g., "okta", "oidc") - Required, must use `NEXT_PUBLIC_` prefix. Not sensitive data - it's just an identifier.
+  - `BETTER_AUTH_URL` - Application base URL
+  - `BETTER_AUTH_SECRET` - Secret for token encryption
 
 ### API Calls Failing
 

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.5/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
@@ -11,10 +11,20 @@
   },
   "overrides": [
     {
-      "includes": ["src/generated/core/bodySerializer.gen.ts"],
+      "includes": ["src/generated/**"],
       "linter": {
         "enabled": false
       }
+    },
+    {
+      "includes": ["src/mocks/**"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noConsole": "off"
+          }
+        }
+      }
     }
   ],
   "formatter": {

dev-auth/README.md

@@ -40,6 +40,9 @@ The provider is pre-configured with:
 
 Replace this with a real OIDC provider (Okta, Keycloak, Auth0, etc.) by updating the environment variables in `.env.local`:
 
-- `OIDC_ISSUER`
-- `OIDC_CLIENT_ID`
-- `OIDC_CLIENT_SECRET`
+- `OIDC_ISSUER_URL` - OIDC provider URL
+- `OIDC_CLIENT_ID` - OAuth2 client ID
+- `OIDC_CLIENT_SECRET` - OAuth2 client secret
+- `NEXT_PUBLIC_OIDC_PROVIDER_ID` - Provider identifier (e.g., "okta", "oidc") - **Required**, must use `NEXT_PUBLIC_` prefix. Not sensitive data - it's just an identifier.
+- `BETTER_AUTH_URL` - Application base URL (e.g., `http://localhost:3000`)
+- `BETTER_AUTH_SECRET` - Secret for token encryption

dev-auth/oidc-provider.mjs

@@ -32,6 +32,7 @@ const configuration = {
         "http://localhost:3001/api/auth/oauth2/callback/oidc",
         "http://localhost:3002/api/auth/oauth2/callback/oidc",
         "http://localhost:3003/api/auth/oauth2/callback/oidc",
+        "http://localhost:3000/api/auth/oauth2/callback/okta",
       ],
       response_types: ["code"],
       grant_types: ["authorization_code", "refresh_token"],

package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "concurrently -n \"OIDC,Mock,Next\" -c \"blue,magenta,green\" \"pnpm oidc\" \"pnpm mock:server\" \"pnpm dev:next\"",
     "dev:next": "next dev",
+    "dev:mock-server": "concurrently -n \"Mock,Next\" -c \"magenta,green\" \"pnpm mock:server\" \"pnpm dev:next\"",
     "build": "next build",
     "start": "next start",
     "lint": "biome check",
@@ -22,6 +23,7 @@
   "dependencies": {
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-slot": "^1.2.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "better-auth": "1.4.0-beta.25",

pnpm-lock.yaml

@@ -0,0 +1,78 @@
+import { cookies } from "next/headers";
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+import { refreshAccessToken } from "@/lib/auth/auth";
+import { BETTER_AUTH_SECRET, COOKIE_NAME } from "@/lib/auth/constants";
+import type { OidcTokenData } from "@/lib/auth/types";
+import { decrypt } from "@/lib/auth/utils";
+
+/**
+ * API Route Handler to refresh OIDC access token.
+ *
+ * This Route Handler can modify cookies (unlike Server Actions during render).
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const { userId } = body;
+
+    if (!userId) {
+      return NextResponse.json({ error: "Missing userId" }, { status: 400 });
+    }
+
+    const cookieStore = await cookies();
+    const encryptedCookie = cookieStore.get(COOKIE_NAME);
+
+    if (!encryptedCookie?.value) {
+      return NextResponse.json({ error: "No token found" }, { status: 401 });
+    }
+
+    let tokenData: OidcTokenData;
+    try {
+      tokenData = await decrypt(encryptedCookie.value, BETTER_AUTH_SECRET);
+    } catch (error) {
+      console.error("[Refresh API] Token decryption failed:", error);
+      cookieStore.delete(COOKIE_NAME);
+      return NextResponse.json({ error: "Invalid token" }, { status: 401 });
+    }
+
+    if (tokenData.userId !== userId) {
+      console.error("[Refresh API] Token userId mismatch");
+      cookieStore.delete(COOKIE_NAME);
+      return NextResponse.json({ error: "Invalid token" }, { status: 401 });
+    }
+
+    if (!tokenData.refreshToken) {
+      console.error("[Refresh API] No refresh token available");
+      cookieStore.delete(COOKIE_NAME);
+      return NextResponse.json({ error: "No refresh token" }, { status: 401 });
+    }
+
+    // Call refreshAccessToken which will save the new token in the cookie
+    const refreshedData = await refreshAccessToken(
+      tokenData.refreshToken,
+      userId,
+      tokenData.refreshTokenExpiresAt,
+    );
+
+    if (!refreshedData) {
+      console.error("[Refresh API] Token refresh failed");
+      cookieStore.delete(COOKIE_NAME);
+      return NextResponse.json(
+        { error: "[Refresh API] Refresh failed" },
+        { status: 401 },
+      );
+    }
+
+    return NextResponse.json({
+      success: true,
+      accessToken: refreshedData.accessToken,
+    });
+  } catch (error) {
+    console.error("[Refresh API] Error during token refresh:", error);
+    return NextResponse.json(
+      { error: "Internal server error" },
+      { status: 500 },
+    );
+  }
+}

src/app/api/auth/refresh-token/route.ts

@@ -1,28 +1,54 @@
 "use server";
 
-import { getRegistryV01Servers } from "@/generated/sdk.gen";
+import type { V0ServerJson } from "@/generated/types.gen";
+import { getAuthenticatedClient } from "@/lib/api-client";
+
+export async function getServers(): Promise<V0ServerJson[]> {
+  const api = await getAuthenticatedClient();
+  const resp = await api.getRegistryV01Servers({
+    client: api.client,
+  });
+
+  if (resp.error) {
+    console.error("[catalog] Failed to fetch servers:", resp.error);
+    return [];
+  }
+
+  if (!resp.data) {
+    return [];
+  }
+
+  const data = resp.data;
+  const items = Array.isArray(data?.servers) ? data.servers : [];
+
+  // Extract the server objects from the response
+  return items
+    .map((item) => item?.server)
+    .filter((server): server is V0ServerJson => server != null);
+}
 
 export async function getServersSummary() {
-  try {
-    const resp = await getRegistryV01Servers();
-    const data = resp.data;
-    const items = Array.isArray(data?.servers) ? data.servers : [];
-
-    const titles = items
-      .map((it) => it?.server?.title ?? it?.server?.name)
-      .filter((t): t is string => typeof t === "string")
-      .slice(0, 5);
-
-    const sample = items.slice(0, 5).map((it) => ({
-      title: it?.server?.title ?? it?.server?.name ?? "Unknown",
-      name: it?.server?.name ?? "unknown",
-      version: it?.server?.version,
-    }));
-
-    return { count: items.length, titles, sample };
-  } catch (error) {
-    // Log the error for debugging
-    console.error("[catalog] Failed to fetch servers:", error);
+  const api = await getAuthenticatedClient();
+  const resp = await api.getRegistryV01Servers({ client: api.client });
+
+  if (resp.error) {
+    console.error("[catalog] Failed to fetch servers:", resp.error);
+    return { count: 0, titles: [], sample: [] };
+  }
+
+  if (!resp.data) {
     return { count: 0, titles: [], sample: [] };
   }
+
+  const items = Array.isArray(resp.data?.servers) ? resp.data.servers : [];
+
+  const sample = items.slice(0, 5).map((it) => ({
+    title: it?.server?.title ?? it?.server?.name ?? "Unknown",
+    name: it?.server?.name ?? "unknown",
+    version: it?.server?.version,
+  }));
+
+  const titles = sample.map((s) => s.title);
+
+  return { count: items.length, titles, sample };
 }