@htlkg/astro 0.0.1

package/src/middleware/route-guards.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Unit tests for route guard middleware
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { requireAuth, requireAdminAccess, requireBrandAccess } from './route-guards.js';
+
+describe('Route Guard Helper Functions', () => {
+	describe('requireAuth', () => {
+		it('should return user when authenticated', async () => {
+			const mockUser = {
+				username: 'testuser',
+				email: 'test@example.com',
+				brandIds: [1, 2],
+				accountIds: [1],
+				isAdmin: false,
+				roles: ['user'],
+			};
+
+			const context = {
+				locals: { user: mockUser },
+				url: { pathname: '/dashboard', search: '' },
+				redirect: vi.fn(),
+			};
+
+			const result = await requireAuth(context);
+			expect(result).toEqual(mockUser);
+			expect(context.redirect).not.toHaveBeenCalled();
+		});
+
+		it('should redirect to login when not authenticated', async () => {
+			const context = {
+				locals: { user: null },
+				url: { pathname: '/dashboard', search: '?tab=settings' },
+				redirect: vi.fn((url) => ({ type: 'redirect', url })),
+			};
+
+			const result = await requireAuth(context);
+			expect(context.redirect).toHaveBeenCalledWith('/login?redirect=%2Fdashboard%3Ftab%3Dsettings');
+		});
+
+		it('should use custom login URL', async () => {
+			const context = {
+				locals: { user: null },
+				url: { pathname: '/dashboard', search: '' },
+				redirect: vi.fn((url) => ({ type: 'redirect', url })),
+			};
+
+			await requireAuth(context, '/custom-login');
+			expect(context.redirect).toHaveBeenCalledWith('/custom-login?redirect=%2Fdashboard');
+		});
+	});
+
+	describe('requireAdminAccess', () => {
+		it('should return user when user is admin', async () => {
+			const mockUser = {
+				username: 'admin',
+				email: 'admin@example.com',
+				brandIds: [],
+				accountIds: [1],
+				isAdmin: true,
+				roles: ['admin'],
+			};
+
+			const context = {
+				locals: { user: mockUser },
+				url: { pathname: '/admin', search: '' },
+				redirect: vi.fn(),
+			};
+
+			const result = await requireAdminAccess(context);
+			expect(result).toEqual(mockUser);
+			expect(context.redirect).not.toHaveBeenCalled();
+		});
+
+		it('should redirect when user is not authenticated', async () => {
+			const context = {
+				locals: { user: null },
+				url: { pathname: '/admin', search: '' },
+				redirect: vi.fn((url) => ({ type: 'redirect', url })),
+			};
+
+			await requireAdminAccess(context);
+			expect(context.redirect).toHaveBeenCalledWith('/login?error=not_authenticated');
+		});
+
+		it('should redirect when user is not admin', async () => {
+			const mockUser = {
+				username: 'user',
+				email: 'user@example.com',
+				brandIds: [1],
+				accountIds: [1],
+				isAdmin: false,
+				roles: ['user'],
+			};
+
+			const context = {
+				locals: { user: mockUser },
+				url: { pathname: '/admin', search: '' },
+				redirect: vi.fn((url) => ({ type: 'redirect', url })),
+			};
+
+			await requireAdminAccess(context);
+			expect(context.redirect).toHaveBeenCalledWith('/login?error=admin_required');
+		});
+	});
+
+	describe('requireBrandAccess', () => {
+		it('should return user when user has brand access', async () => {
+			const mockUser = {
+				username: 'user',
+				email: 'user@example.com',
+				brandIds: [1, 2, 3],
+				accountIds: [1],
+				isAdmin: false,
+				roles: ['user'],
+			};
+
+			const context = {
+				locals: { user: mockUser },
+				url: { pathname: '/brands/2', search: '' },
+				redirect: vi.fn(),
+			};
+
+			const result = await requireBrandAccess(context, 2);
+			expect(result).toEqual(mockUser);
+			expect(context.redirect).not.toHaveBeenCalled();
+		});
+
+		it('should return user when user is admin (even without brand access)', async () => {
+			const mockUser = {
+				username: 'admin',
+				email: 'admin@example.com',
+				brandIds: [],
+				accountIds: [1],
+				isAdmin: true,
+				roles: ['admin'],
+			};
+
+			const context = {
+				locals: { user: mockUser },
+				url: { pathname: '/brands/5', search: '' },
+				redirect: vi.fn(),
+			};
+
+			const result = await requireBrandAccess(context, 5);
+			expect(result).toEqual(mockUser);
+			expect(context.redirect).not.toHaveBeenCalled();
+		});
+
+		it('should redirect when user is not authenticated', async () => {
+			const context = {
+				locals: { user: null },
+				url: { pathname: '/brands/1', search: '' },
+				redirect: vi.fn((url) => ({ type: 'redirect', url })),
+			};
+
+			await requireBrandAccess(context, 1);
+			expect(context.redirect).toHaveBeenCalledWith('/login?error=not_authenticated');
+		});
+
+		it('should redirect when user does not have brand access', async () => {
+			const mockUser = {
+				username: 'user',
+				email: 'user@example.com',
+				brandIds: [1, 2],
+				accountIds: [1],
+				isAdmin: false,
+				roles: ['user'],
+			};
+
+			const context = {
+				locals: { user: mockUser },
+				url: { pathname: '/brands/5', search: '' },
+				redirect: vi.fn((url) => ({ type: 'redirect', url })),
+			};
+
+			await requireBrandAccess(context, 5);
+			expect(context.redirect).toHaveBeenCalledWith('/login?error=access_denied');
+		});
+	});
+});

package/src/middleware/route-guards.ts

@@ -0,0 +1,218 @@
+/**
+ * Route guard middleware for htlkg integration
+ * 
+ * This middleware enforces access control based on route configuration:
+ * - Public routes: accessible to everyone
+ * - Authenticated routes: require any logged-in user
+ * - Admin routes: require admin privileges
+ * - Brand routes: require brand-specific access or admin privileges
+ */
+
+import type { MiddlewareHandler } from 'astro';
+import type { RoutePattern, RouteGuardConfig } from '../htlkg/config.js';
+
+// Import configuration from virtual module
+import { routeGuardConfig } from 'virtual:htlkg-config';
+
+// Type assertion for the imported config
+const config = routeGuardConfig as RouteGuardConfig;
+
+/**
+ * Helper: Check if pathname matches any of the provided patterns
+ */
+function matchesPattern(pathname: string, patterns: RoutePattern[]): boolean {
+	return patterns.some((pattern) => {
+		try {
+			if (typeof pattern === 'string') {
+				// Special case: "/" only matches exactly
+				if (pattern === '/') {
+					return pathname === '/';
+				}
+				// String pattern: exact match or starts with (for sub-routes)
+				return pathname === pattern || pathname.startsWith(pattern + '/');
+			}
+			// RegExp pattern: test against pathname
+			return pattern.test(pathname);
+		} catch (error) {
+			// Log pattern matching errors but don't block the request
+			console.error(
+				'[htlkg Route Guard] Error matching pattern:',
+				error instanceof Error ? error.message : 'Unknown error',
+			);
+			return false;
+		}
+	});
+}
+
+/**
+ * Route guard middleware - protects routes based on configuration
+ * 
+ * This middleware runs after authMiddleware and enforces access control
+ * based on the route configuration provided to the htlkg integration.
+ * 
+ * @example
+ * // In astro.config.mjs
+ * htlkg({
+ *   auth: {
+ *     publicRoutes: ['/login', '/'],
+ *     adminRoutes: [/^\/admin/],
+ *     brandRoutes: [
+ *       { pattern: /^\/brands\/(\d+)/, brandIdParam: 1 }
+ *     ],
+ *     loginUrl: '/login'
+ *   }
+ * })
+ */
+export const routeGuard: MiddlewareHandler = async (context, next) => {
+	const { locals, url, redirect } = context;
+	const pathname = url.pathname;
+
+	const {
+		publicRoutes = [],
+		authenticatedRoutes = [],
+		adminRoutes = [],
+		brandRoutes = [],
+		loginUrl = '/login',
+	} = config;
+
+	try {
+		// Public routes - no auth required
+		if (matchesPattern(pathname, publicRoutes)) {
+			console.log(`[htlkg Route Guard] Public route: ${pathname}`);
+			return next();
+		}
+
+		const user = locals.user;
+
+		// Admin routes - require admin role
+		if (matchesPattern(pathname, adminRoutes)) {
+			if (!user || !user.isAdmin) {
+				console.log(
+					`[htlkg Route Guard] Admin access denied for ${pathname} - User: ${user ? 'authenticated (non-admin)' : 'not authenticated'}`,
+				);
+				return redirect(`${loginUrl}?error=admin_required`);
+			}
+			console.log(
+				`[htlkg Route Guard] Admin access granted for ${pathname}`,
+			);
+			return next();
+		}
+
+		// Brand routes - require brand access or admin
+		for (const brandRoute of brandRoutes) {
+			try {
+				const match = pathname.match(brandRoute.pattern);
+				if (match) {
+					const brandId = Number.parseInt(match[brandRoute.brandIdParam], 10);
+
+					if (Number.isNaN(brandId)) {
+						console.warn(
+							`[htlkg Route Guard] Invalid brandId extracted from ${pathname}`,
+						);
+						return redirect(`${loginUrl}?error=invalid_brand`);
+					}
+
+					if (!user || (!user.isAdmin && !user.brandIds.includes(brandId))) {
+						console.log(
+							`[htlkg Route Guard] Brand access denied for ${pathname} (brandId: ${brandId}) - User: ${user ? `authenticated (brandIds: ${user.brandIds.join(',')})` : 'not authenticated'}`,
+						);
+						return redirect(`${loginUrl}?error=access_denied`);
+					}
+					console.log(
+						`[htlkg Route Guard] Brand access granted for ${pathname} (brandId: ${brandId})`,
+					);
+					return next();
+				}
+			} catch (error) {
+				console.error(
+					`[htlkg Route Guard] Error processing brand route for ${pathname}:`,
+					error instanceof Error ? error.message : 'Unknown error',
+				);
+				// Fail-safe: deny access on error
+				return redirect(`${loginUrl}?error=access_denied`);
+			}
+		}
+
+		// Authenticated routes - require any logged-in user
+		if (matchesPattern(pathname, authenticatedRoutes)) {
+			if (!user) {
+				const returnUrl = encodeURIComponent(pathname + url.search);
+				console.log(
+					`[htlkg Route Guard] Authentication required for ${pathname}, redirecting to login`,
+				);
+				return redirect(`${loginUrl}?redirect=${returnUrl}`);
+			}
+			console.log(
+				`[htlkg Route Guard] Authenticated access granted for ${pathname}`,
+			);
+			return next();
+		}
+
+		// Default: allow access
+		console.log(
+			`[htlkg Route Guard] Default access granted for ${pathname}`,
+		);
+		return next();
+	} catch (error) {
+		// Catch-all error handler for route guard
+		console.error(
+			'[htlkg Route Guard] Unexpected error in route guard:',
+			error instanceof Error ? error.message : 'Unknown error',
+		);
+		// Fail-safe: deny access and redirect to login
+		return redirect(`${loginUrl}?error=server_error`);
+	}
+};
+
+/**
+ * Helper functions for programmatic route protection in pages
+ * These can be used in Astro pages for more fine-grained control
+ */
+
+/**
+ * Require authentication for a page
+ * Redirects to login if user is not authenticated
+ */
+export async function requireAuth(context: any, loginUrl = '/login') {
+	const user = context.locals.user;
+	if (!user) {
+		const currentUrl = context.url.pathname + context.url.search;
+		const encodedReturnUrl = encodeURIComponent(currentUrl);
+		return context.redirect(`${loginUrl}?redirect=${encodedReturnUrl}`);
+	}
+	return user;
+}
+
+/**
+ * Require admin access for a page
+ * Redirects to login if user is not an admin
+ */
+export async function requireAdminAccess(context: any, loginUrl = '/login') {
+	const user = context.locals.user;
+	if (!user) {
+		return context.redirect(`${loginUrl}?error=not_authenticated`);
+	}
+	if (!user.isAdmin) {
+		return context.redirect(`${loginUrl}?error=admin_required`);
+	}
+	return user;
+}
+
+/**
+ * Require brand access for a page
+ * Redirects to login if user doesn't have access to the specified brand
+ */
+export async function requireBrandAccess(
+	context: any,
+	brandId: number,
+	loginUrl = '/login'
+) {
+	const user = context.locals.user;
+	if (!user) {
+		return context.redirect(`${loginUrl}?error=not_authenticated`);
+	}
+	if (!user.isAdmin && !user.brandIds.includes(brandId)) {
+		return context.redirect(`${loginUrl}?error=access_denied`);
+	}
+	return user;
+}

package/src/patterns/admin/DetailPage.astro

@@ -0,0 +1,195 @@
+---
+/**
+ * Admin Detail Page Pattern
+ *
+ * Standard pattern for admin detail pages with tabs and content sections.
+ * Provides consistent structure for entity detail pages.
+ *
+ * @example
+ * ```astro
+ * <DetailPage
+ *   title="User Details"
+ *   description="View and edit user information"
+ *   user={user}
+ *   tabs={tabs}
+ *   activeTab="overview"
+ * >
+ *   <div slot="actions">
+ *     <button>Edit</button>
+ *   </div>
+ *   <div slot="content">
+ *     <UserOverview />
+ *   </div>
+ * </DetailPage>
+ * ```
+ */
+
+import AdminLayout from "../../layouts/AdminLayout.astro";
+import PageHeader from "../../components/PageHeader.astro";
+import type { AuthUser } from "@htlkg/core/types";
+
+interface BreadcrumbItem {
+  label: string;
+  href?: string;
+}
+
+interface Tab {
+  id: string;
+  label: string;
+  href: string;
+}
+
+interface Props {
+  title: string;
+  description?: string;
+  user: AuthUser;
+  currentPage?: string;
+  breadcrumbs?: BreadcrumbItem[];
+  tabs?: Tab[];
+  activeTab?: string;
+}
+
+const {
+  title,
+  description,
+  user,
+  currentPage,
+  breadcrumbs = [],
+  tabs = [],
+  activeTab,
+} = Astro.props;
+---
+
+<AdminLayout
+  title={title}
+  description={description}
+  user={user}
+  currentPage={currentPage}
+>
+  <div slot="actions">
+    <slot name="actions" />
+  </div>
+
+  <div class="detail-page">
+    <PageHeader
+      title={title}
+      description={description}
+      breadcrumbs={breadcrumbs}
+    />
+
+    {
+      tabs.length > 0 && (
+        <nav class="detail-tabs">
+          {tabs.map((tab) => (
+            <a
+              href={tab.href}
+              class:list={["tab-item", { active: activeTab === tab.id }]}
+            >
+              {tab.label}
+            </a>
+          ))}
+        </nav>
+      )
+    }
+
+    <div class="detail-content">
+      <slot name="content" />
+    </div>
+
+    <div class="detail-sidebar">
+      <slot name="sidebar" />
+    </div>
+  </div>
+</AdminLayout>
+
+<style>
+  .detail-page {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1.5rem;
+  }
+
+  .detail-tabs {
+    display: flex;
+    gap: 2rem;
+    border-bottom: 1px solid #e5e7eb;
+    background: white;
+    padding: 0 1.5rem;
+    border-radius: 0.5rem 0.5rem 0 0;
+  }
+
+  .tab-item {
+    padding: 1rem 0;
+    color: #6b7280;
+    text-decoration: none;
+    font-weight: 500;
+    border-bottom: 2px solid transparent;
+    transition: all 0.2s;
+    position: relative;
+    top: 1px;
+  }
+
+  .tab-item:hover {
+    color: #111827;
+  }
+
+  .tab-item.active {
+    color: #2563eb;
+    border-bottom-color: #2563eb;
+  }
+
+  .detail-content {
+    background: white;
+    border-radius: 0.5rem;
+    border: 1px solid #e5e7eb;
+    padding: 1.5rem;
+  }
+
+  .detail-sidebar {
+    background: white;
+    border-radius: 0.5rem;
+    border: 1px solid #e5e7eb;
+    padding: 1.5rem;
+  }
+
+  /* Two column layout when sidebar has content */
+  .detail-page:has(.detail-sidebar:not(:empty)) {
+    grid-template-columns: 1fr 20rem;
+    grid-template-areas:
+      "header header"
+      "tabs tabs"
+      "content sidebar";
+  }
+
+  .detail-page:has(.detail-sidebar:not(:empty)) .detail-content {
+    grid-area: content;
+  }
+
+  .detail-page:has(.detail-sidebar:not(:empty)) .detail-sidebar {
+    grid-area: sidebar;
+  }
+
+  /* Responsive */
+  @media (max-width: 1024px) {
+    .detail-page:has(.detail-sidebar:not(:empty)) {
+      grid-template-columns: 1fr;
+      grid-template-areas:
+        "header"
+        "tabs"
+        "content"
+        "sidebar";
+    }
+  }
+
+  @media (max-width: 768px) {
+    .detail-tabs {
+      overflow-x: auto;
+      gap: 1rem;
+      padding: 0 1rem;
+    }
+
+    .tab-item {
+      white-space: nowrap;
+    }
+  }
+</style>