Authentication & Authorization Architecture

import { IronSessionOptions } from "iron-session";

export interface SessionData {
  userId: string;
  email: string;
  roles: string[];
  isLoggedIn: boolean;
}

export const sessionOptions: IronSessionOptions = {
  password: process.env.SESSION_SECRET as string, // 32+ chars
  cookieName: "__Host-app-session",
  cookieOptions: {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    maxAge: 60 * 60 * 24 * 7, // 7 days
    path: "/",
  },
};

import { getIronSession } from "iron-session";
import { cookies } from "next/headers";
import { NextResponse } from "next/server";
import { sessionOptions, SessionData } from "@/lib/session";
import { verifyCredentials } from "@/lib/db";

export async function POST(req: Request) {
  const { email, password } = await req.json();

  const user = await verifyCredentials(email, password);
  if (!user) {
    return NextResponse.json({ error: "Invalid credentials" }, { status: 401 });
  }

  const session = await getIronSession<SessionData>(cookies(), sessionOptions);
  session.userId = user.id;
  session.email = user.email;
  session.roles = user.roles;
  session.isLoggedIn = true;
  await session.save();

  return NextResponse.json({ ok: true });
}

import { createClient } from "redis";
import RedisStore from "connect-redis";
import session from "express-session";

const redisClient = createClient({
  url: process.env.REDIS_URL,
});
redisClient.connect();

export const sessionMiddleware = session({
  store: new RedisStore({ client: redisClient }),
  secret: process.env.SESSION_SECRET as string,
  resave: false,
  saveUninitialized: false,
  name: "__Host-session-id",
  cookie: {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    maxAge: 1000 * 60 * 60 * 24 * 7, // 7 days in ms
  },
});

// Revoke a session by ID (for logout, account deletion, or security events)
export async function revokeSession(sessionId: string): Promise<void> {
  await redisClient.del(`sess:${sessionId}`);
}

export interface JWTPayload {
  // Standard claims (RFC 7519)
  iss: string;      // Issuer: who created the token ("https://api.myapp.com")
  sub: string;      // Subject: who the token is about (user ID)
  aud: string;      // Audience: who the token is for ("https://app.myapp.com")
  exp: number;      // Expiry: Unix timestamp when the token expires
  iat: number;      // Issued at: Unix timestamp when the token was created
  jti: string;      // JWT ID: unique identifier for this token (for revocation)

  // Custom application claims
  email: string;
  roles: string[];
  permissions: string[];
  tenantId?: string;
}

// Claims that MUST be validated on every request
export const REQUIRED_VALIDATIONS = ["iss", "aud", "exp", "jti"] as const;

import { SignJWT, jwtVerify, generateKeyPair } from "jose";

// Generate RSA key pair (do this once, store securely)
// const { publicKey, privateKey } = await generateKeyPair("RS256");

const ISSUER = process.env.JWT_ISSUER as string;
const AUDIENCE = process.env.JWT_AUDIENCE as string;

export async function signAccessToken(payload: {
  sub: string;
  email: string;
  roles: string[];
  permissions: string[];
  jti: string;
}): Promise<string> {
  const privateKey = await importPrivateKey(process.env.JWT_PRIVATE_KEY as string);

  return new SignJWT(payload)
    .setProtectedHeader({ alg: "RS256" })
    .setIssuer(ISSUER)
    .setAudience(AUDIENCE)
    .setIssuedAt()
    .setExpirationTime("15m") // Short-lived access token
    .sign(privateKey);
}

export async function verifyAccessToken(token: string): Promise<JWTPayload> {
  const publicKey = await importPublicKey(process.env.JWT_PUBLIC_KEY as string);

  const { payload } = await jwtVerify(token, publicKey, {
    issuer: ISSUER,
    audience: AUDIENCE,
    algorithms: ["RS256"],
  });

  return payload as unknown as JWTPayload;
}

async function importPrivateKey(pem: string): Promise<CryptoKey> {
  const { importPKCS8 } = await import("jose");
  return importPKCS8(pem, "RS256");
}

async function importPublicKey(pem: string): Promise<CryptoKey> {
  const { importSPKI } = await import("jose");
  return importSPKI(pem, "RS256");
}

import NextAuth from "next-auth";
import Google from "next-auth/providers/google";
import GitHub from "next-auth/providers/github";
import Credentials from "next-auth/providers/credentials";
import { DrizzleAdapter } from "@auth/drizzle-adapter";
import { db } from "@/lib/db";
import { verifyCredentials } from "@/lib/users";

export const { handlers, signIn, signOut, auth } = NextAuth({
  adapter: DrizzleAdapter(db),
  providers: [
    Google({
      clientId: process.env.AUTH_GOOGLE_ID!,
      clientSecret: process.env.AUTH_GOOGLE_SECRET!,
      authorization: {
        params: {
          scope: "openid email profile",
          prompt: "consent",
          access_type: "offline", // request refresh token
        },
      },
    }),
    GitHub({
      clientId: process.env.AUTH_GITHUB_ID!,
      clientSecret: process.env.AUTH_GITHUB_SECRET!,
    }),
    Credentials({
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" },
      },
      authorize: async (credentials) => {
        const user = await verifyCredentials(
          credentials.email as string,
          credentials.password as string
        );
        return user ?? null;
      },
    }),
  ],
  callbacks: {
    jwt({ token, user, trigger, session }) {
      if (user) {
        // Called on sign in: enrich token with custom claims
        token.roles = (user as { roles?: string[] }).roles ?? [];
        token.permissions = (user as { permissions?: string[] }).permissions ?? [];
      }
      if (trigger === "update" && session) {
        // Called when session.update() is triggered
        token.roles = session.roles;
      }
      return token;
    },
    session({ session, token }) {
      session.user.roles = token.roles as string[];
      session.user.permissions = token.permissions as string[];
      return session;
    },
  },
  session: {
    strategy: "jwt",
    maxAge: 30 * 24 * 60 * 60, // 30 days
  },
  pages: {
    signIn: "/login",
    error: "/login",
  },
});

import { handlers } from "@/lib/auth";

export const { GET, POST } = handlers;

import axios from "axios";

const api = axios.create({ baseURL: "/api" });

let refreshPromise: Promise<string> | null = null;

api.interceptors.response.use(
  (response) => response,
  async (error) => {
    const original = error.config;

    // 401 on a request that has not been retried yet
    if (error.response?.status === 401 && !original._retry) {
      original._retry = true;

      // Deduplicate concurrent refresh attempts
      if (!refreshPromise) {
        refreshPromise = refreshAccessToken().finally(() => {
          refreshPromise = null;
        });
      }

      try {
        const newAccessToken = await refreshPromise;
        // Store in memory only, never localStorage
        tokenStore.set(newAccessToken);
        original.headers["Authorization"] = `Bearer ${newAccessToken}`;
        return api(original);
      } catch {
        // Refresh failed: redirect to login
        tokenStore.clear();
        window.location.href = "/login";
        return Promise.reject(error);
      }
    }

    return Promise.reject(error);
  }
);

async function refreshAccessToken(): Promise<string> {
  // Refresh token is in httpOnly cookie, sent automatically
  const res = await fetch("/api/auth/refresh", { method: "POST" });
  if (!res.ok) throw new Error("Refresh failed");
  const data = await res.json();
  return data.accessToken;
}

// In-memory token store: survives JS execution, not page reload
const tokenStore = {
  _token: null as string | null,
  get: () => tokenStore._token,
  set: (t: string) => { tokenStore._token = t; },
  clear: () => { tokenStore._token = null; },
};

// Attach token to every request
api.interceptors.request.use((config) => {
  const token = tokenStore.get();
  if (token) config.headers["Authorization"] = `Bearer ${token}`;
  return config;
});

export { api, tokenStore };

import { NextResponse } from "next/server";
import { cookies } from "next/headers";

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const code = searchParams.get("code");
  const state = searchParams.get("state");

  // Validate state parameter against stored value (CSRF protection)
  const cookieStore = cookies();
  const storedState = cookieStore.get("oauth_state")?.value;
  if (!state || state !== storedState) {
    return NextResponse.redirect("/login?error=invalid_state");
  }

  const codeVerifier = cookieStore.get("pkce_verifier")?.value;
  if (!code || !codeVerifier) {
    return NextResponse.redirect("/login?error=missing_params");
  }

  // Exchange code for tokens server-side (code_verifier never leaves server)
  const tokenRes = await fetch(process.env.AUTH_TOKEN_ENDPOINT!, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code,
      redirect_uri: process.env.AUTH_REDIRECT_URI!,
      client_id: process.env.AUTH_CLIENT_ID!,
      code_verifier: codeVerifier,
    }),
  });

  if (!tokenRes.ok) {
    return NextResponse.redirect("/login?error=token_exchange_failed");
  }

  const tokens = await tokenRes.json();

  const response = NextResponse.redirect("/dashboard");

  // Store tokens in httpOnly cookies - JS cannot read these
  response.cookies.set("access_token", tokens.access_token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    maxAge: 15 * 60, // 15 minutes
    path: "/",
  });

  response.cookies.set("refresh_token", tokens.refresh_token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    maxAge: 30 * 24 * 60 * 60, // 30 days
    path: "/api/auth/refresh", // restrict to refresh endpoint only
  });

  // Clear PKCE cookies
  response.cookies.delete("pkce_verifier");
  response.cookies.delete("oauth_state");

  return response;
}

import { cookies } from "next/headers";
import { NextRequest, NextResponse } from "next/server";
import { verifyAndRefreshToken } from "@/lib/token-server";

const UPSTREAM_API = process.env.UPSTREAM_API_URL!;

export async function GET(req: NextRequest, { params }: { params: { path: string[] } }) {
  return proxyRequest(req, "GET", params.path);
}

export async function POST(req: NextRequest, { params }: { params: { path: string[] } }) {
  return proxyRequest(req, "POST", params.path);
}

async function proxyRequest(req: NextRequest, method: string, path: string[]) {
  const cookieStore = cookies();
  const accessToken = cookieStore.get("access_token")?.value;

  if (!accessToken) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Verify token and auto-refresh if expired (server-side, invisible to client)
  const validToken = await verifyAndRefreshToken(accessToken);
  if (!validToken) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const upstreamUrl = `${UPSTREAM_API}/${path.join("/")}${req.nextUrl.search}`;
  const body = method !== "GET" ? await req.text() : undefined;

  const upstream = await fetch(upstreamUrl, {
    method,
    headers: {
      "Authorization": `Bearer ${validToken}`,
      "Content-Type": req.headers.get("Content-Type") ?? "application/json",
    },
    body,
  });

  const data = await upstream.json();
  return NextResponse.json(data, { status: upstream.status });
}

import { randomBytes, createHmac } from "crypto";

const CSRF_SECRET = process.env.CSRF_SECRET as string;

export function generateCsrfToken(sessionId: string): string {
  const random = randomBytes(32).toString("hex");
  // Bind CSRF token to the session to prevent token substitution attacks
  const hmac = createHmac("sha256", CSRF_SECRET)
    .update(`${sessionId}:${random}`)
    .digest("hex");
  return `${random}.${hmac}`;
}

export function verifyCsrfToken(token: string, sessionId: string): boolean {
  const [random, hmac] = token.split(".");
  if (!random || !hmac) return false;

  const expected = createHmac("sha256", CSRF_SECRET)
    .update(`${sessionId}:${random}`)
    .digest("hex");

  // Constant-time comparison to prevent timing attacks
  return expected.length === hmac.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(hmac));
}

function timingSafeEqual(a: Buffer, b: Buffer): boolean {
  if (a.length !== b.length) return false;
  let result = 0;
  for (let i = 0; i < a.length; i++) {
    result |= a[i] ^ b[i];
  }
  return result === 0;
}

export type Permission =
  | "posts:read"
  | "posts:write"
  | "posts:delete"
  | "users:read"
  | "users:write"
  | "users:delete"
  | "admin:all";

export type Role = "viewer" | "editor" | "admin" | "super_admin";

export const ROLE_PERMISSIONS: Record<Role, Permission[]> = {
  viewer: ["posts:read"],
  editor: ["posts:read", "posts:write", "users:read"],
  admin: ["posts:read", "posts:write", "posts:delete", "users:read", "users:write"],
  super_admin: ["posts:read", "posts:write", "posts:delete", "users:read", "users:write", "users:delete", "admin:all"],
};

export function hasPermission(userRoles: Role[], permission: Permission): boolean {
  return userRoles.some((role) => {
    const perms = ROLE_PERMISSIONS[role] ?? [];
    return perms.includes(permission) || perms.includes("admin:all");
  });
}

export function hasAnyPermission(userRoles: Role[], permissions: Permission[]): boolean {
  return permissions.some((p) => hasPermission(userRoles, p));
}

export function hasAllPermissions(userRoles: Role[], permissions: Permission[]): boolean {
  return permissions.every((p) => hasPermission(userRoles, p));
}

import { useSession } from "next-auth/react";
import { hasPermission, hasAnyPermission, Permission, Role } from "@/lib/permissions";

export function usePermissions() {
  const { data: session } = useSession();
  const userRoles = (session?.user?.roles ?? []) as Role[];

  return {
    can: (permission: Permission) => hasPermission(userRoles, permission),
    canAny: (permissions: Permission[]) => hasAnyPermission(userRoles, permissions),
    roles: userRoles,
    isLoggedIn: !!session,
  };
}

// Usage in a component:
// const { can } = usePermissions();
// {can("posts:write") && <button>Edit Post</button>}

import { usePermissions } from "@/hooks/usePermissions";
import type { Permission } from "@/lib/permissions";

interface PermissionGuardProps {
  require: Permission | Permission[];
  requireAll?: boolean;
  fallback?: React.ReactNode;
  children: React.ReactNode;
}

export function PermissionGuard({
  require,
  requireAll = false,
  fallback = null,
  children,
}: PermissionGuardProps) {
  const { can, canAny } = usePermissions();
  const permissions = Array.isArray(require) ? require : [require];

  const allowed = requireAll
    ? permissions.every((p) => can(p))
    : canAny(permissions);

  return allowed ? <>{children}</> : <>{fallback}</>;
}

// Usage:
// <PermissionGuard require="posts:delete" fallback={<p>No access</p>}>
//   <DeleteButton />
// </PermissionGuard>

import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/lib/auth";

const PUBLIC_PATHS = ["/", "/login", "/register", "/api/auth"];
const ADMIN_PATHS = ["/admin"];

export async function middleware(req: NextRequest) {
  const { pathname } = req.nextUrl;

  // Allow public paths through without auth check
  if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) {
    return NextResponse.next();
  }

  const session = await auth();

  // Not authenticated: redirect to login with return URL
  if (!session) {
    const loginUrl = new URL("/login", req.url);
    loginUrl.searchParams.set("callbackUrl", pathname);
    return NextResponse.redirect(loginUrl);
  }

  // Admin paths require admin role
  if (ADMIN_PATHS.some((p) => pathname.startsWith(p))) {
    const isAdmin = session.user.roles?.includes("admin") ||
      session.user.roles?.includes("super_admin");
    if (!isAdmin) {
      return NextResponse.redirect(new URL("/403", req.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  // Match all paths except static files and Next.js internals
  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\.png$).*)"],
};

import { Navigate, useLocation } from "react-router-dom";
import { useAuth } from "@/hooks/useAuth";
import type { Role } from "@/lib/permissions";

interface ProtectedRouteProps {
  children: React.ReactNode;
  requiredRoles?: Role[];
}

export function ProtectedRoute({ children, requiredRoles }: ProtectedRouteProps) {
  const { isAuthenticated, isLoading, user } = useAuth();
  const location = useLocation();

  if (isLoading) {
    return <LoadingScreen />;
  }

  if (!isAuthenticated) {
    // Preserve the intended destination for post-login redirect
    return <Navigate to="/login" state={{ from: location }} replace />;
  }

  if (requiredRoles && !requiredRoles.some((r) => user?.roles.includes(r))) {
    return <Navigate to="/403" replace />;
  }

  return <>{children}</>;
}

// Usage with React Router:
// <Route path="/dashboard" element={
//   <ProtectedRoute>
//     <Dashboard />
//   </ProtectedRoute>
// } />
//
// <Route path="/admin" element={
//   <ProtectedRoute requiredRoles={["admin"]}>
//     <AdminPanel />
//   </ProtectedRoute>
// } />

import NextAuth from "next-auth";
import { getTenantConfig } from "@/lib/tenants";

export const { handlers, auth } = NextAuth(async (req) => {
  // Determine tenant from request: subdomain, path param, or stored cookie
  const hostname = req.headers.get("host") ?? "";
  const subdomain = hostname.split(".")[0];
  const tenant = await getTenantConfig(subdomain);

  return {
    providers: tenant
      ? [
          // Dynamic OIDC provider based on tenant configuration
          {
            id: `oidc-${tenant.id}`,
            name: tenant.name,
            type: "oidc",
            issuer: tenant.oidcIssuer,
            clientId: tenant.clientId,
            clientSecret: tenant.clientSecret,
          },
        ]
      : [
          // Fallback to default providers for non-tenant requests
          defaultProviders,
        ],
    callbacks: {
      jwt({ token, user }) {
        if (user) {
          token.tenantId = tenant?.id;
          token.tenantRoles = user.tenantRoles;
        }
        return token;
      },
    },
  };
});

// WRONG: the API does not check permissions
// The button is hidden, but the endpoint is open to any authenticated user

function PostActions({ postId }: { postId: string }) {
  const { can } = usePermissions();
  return (
    <div>
      {can("posts:delete") && (
        <button onClick={() => deletePost(postId)}>Delete</button>
      )}
    </div>
  );
}

// The API route:
export async function DELETE(req: Request, { params }: { params: { id: string } }) {
  const session = await auth();
  if (!session) return new Response(null, { status: 401 });
  // BUG: no permission check here - any authenticated user can delete any post
  await db.post.delete({ where: { id: params.id } });
  return new Response(null, { status: 204 });
}

// CORRECT: UI hides the button AND API enforces the permission

// UI layer (convenience)
function PostActions({ postId }: { postId: string }) {
  const { can } = usePermissions();
  return (
    <div>
      {can("posts:delete") && (
        <button onClick={() => deletePost(postId)}>Delete</button>
      )}
    </div>
  );
}

// API layer (security enforcement)
export async function DELETE(req: Request, { params }: { params: { id: string } }) {
  const session = await auth();
  if (!session) return new Response(null, { status: 401 });

  const canDelete = hasPermission(session.user.roles, "posts:delete");
  if (!canDelete) return new Response(null, { status: 403 });

  await db.post.delete({ where: { id: params.id } });
  return new Response(null, { status: 204 });
}

// PKCE helper for Authorization Code + PKCE flow in a browser SPA

function base64urlEncode(buffer: ArrayBuffer): string {
  return btoa(String.fromCharCode(...new Uint8Array(buffer)))
    .replace(/+/g, "-")
    .replace(///g, "_")
    .replace(/=/g, "");
}

export async function generatePKCE(): Promise<{
  codeVerifier: string;
  codeChallenge: string;
}> {
  const array = new Uint8Array(64);
  crypto.getRandomValues(array);
  const codeVerifier = base64urlEncode(array.buffer);

  const encoded = new TextEncoder().encode(codeVerifier);
  const hash = await crypto.subtle.digest("SHA-256", encoded);
  const codeChallenge = base64urlEncode(hash);

  return { codeVerifier, codeChallenge };
}

export function buildAuthUrl(params: {
  clientId: string;
  redirectUri: string;
  scope: string;
  state: string;
  codeChallenge: string;
}): string {
  const url = new URL(import.meta.env.VITE_AUTH_AUTHORIZATION_ENDPOINT);
  url.searchParams.set("response_type", "code");
  url.searchParams.set("client_id", params.clientId);
  url.searchParams.set("redirect_uri", params.redirectUri);
  url.searchParams.set("scope", params.scope);
  url.searchParams.set("state", params.state);
  url.searchParams.set("code_challenge", params.codeChallenge);
  url.searchParams.set("code_challenge_method", "S256");
  return url.toString();
}

export async function exchangeCodeForTokens(code: string, codeVerifier: string) {
  // In a pure SPA (no BFF), the token exchange must be public (no client_secret)
  // This is secure because the code_verifier cannot be guessed
  const res = await fetch(import.meta.env.VITE_AUTH_TOKEN_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code,
      redirect_uri: import.meta.env.VITE_AUTH_REDIRECT_URI,
      client_id: import.meta.env.VITE_AUTH_CLIENT_ID,
      code_verifier: codeVerifier,
    }),
  });

  if (!res.ok) throw new Error("Token exchange failed");
  return res.json() as Promise<{
    access_token: string;
    refresh_token: string;
    id_token: string;
    expires_in: number;
  }>;
}

import express from "express";
import cookieParser from "cookie-parser";
import { exchangeCodeForTokens, refreshAccessToken } from "./token-service";

const app = express();
app.use(express.json());
app.use(cookieParser(process.env.COOKIE_SECRET));

const COOKIE_OPTS = {
  httpOnly: true,
  secure: process.env.NODE_ENV === "production",
  sameSite: "lax" as const,
};

// Callback: complete the PKCE exchange and store tokens in httpOnly cookies
app.get("/auth/callback", async (req, res) => {
  const { code, state } = req.query as Record<string, string>;

  const stored = req.signedCookies.oauth_state;
  if (!state || state !== stored) {
    return res.redirect("/login?error=invalid_state");
  }

  const codeVerifier = req.signedCookies.pkce_verifier;
  const tokens = await exchangeCodeForTokens(code, codeVerifier);

  res.clearCookie("oauth_state");
  res.clearCookie("pkce_verifier");

  res.cookie("access_token", tokens.access_token, {
    ...COOKIE_OPTS,
    maxAge: tokens.expires_in * 1000,
  });
  res.cookie("refresh_token", tokens.refresh_token, {
    ...COOKIE_OPTS,
    maxAge: 30 * 24 * 60 * 60 * 1000,
    path: "/auth/refresh",
  });

  res.redirect("/");
});

// Silent refresh: SPA calls this when access token is near expiry
app.post("/auth/refresh", async (req, res) => {
  const refreshToken = req.cookies.refresh_token;
  if (!refreshToken) return res.status(401).json({ error: "No refresh token" });

  try {
    const tokens = await refreshAccessToken(refreshToken);
    res.cookie("access_token", tokens.access_token, {
      ...COOKIE_OPTS,
      maxAge: tokens.expires_in * 1000,
    });
    res.json({ ok: true, expiresIn: tokens.expires_in });
  } catch {
    res.clearCookie("access_token");
    res.clearCookie("refresh_token");
    res.status(401).json({ error: "Refresh failed" });
  }
});

app.listen(3001);

import { createRouter, createRoute, redirect } from "@tanstack/react-router";
import { rootRoute } from "./__root";
import { authStore } from "@/lib/auth-store";

const dashboardRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/dashboard",
  beforeLoad: async ({ location }) => {
    if (!authStore.isAuthenticated()) {
      throw redirect({
        to: "/login",
        search: { redirect: location.href },
      });
    }
  },
  component: Dashboard,
});

const adminRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/admin",
  beforeLoad: async () => {
    const user = authStore.getUser();
    if (!user?.roles.includes("admin")) {
      throw redirect({ to: "/403" });
    }
  },
  component: AdminPanel,
});

export const router = createRouter({
  routeTree: rootRoute.addChildren([dashboardRoute, adminRoute]),
});