@htlkg/core 0.0.2 → 0.0.3

package/src/auth/index.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+	hasAccessToBrand,
+	hasAccessToAccount,
+	isAdminUser,
+	isSuperAdminUser,
+	type User,
+} from "./index";
+
+describe("Auth Module", () => {
+	describe("hasAccessToBrand", () => {
+		it("should return false for null user", () => {
+			expect(hasAccessToBrand(null, 1)).toBe(false);
+		});
+
+		it("should return true for admin user", () => {
+			const user: User = {
+				username: "admin",
+				email: "admin@test.com",
+				brandIds: [],
+				accountIds: [],
+				isAdmin: true,
+				isSuperAdmin: false,
+				roles: ["ADMINS"],
+			};
+			expect(hasAccessToBrand(user, 1)).toBe(true);
+		});
+
+		it("should return true if user has brand access", () => {
+			const user: User = {
+				username: "user",
+				email: "user@test.com",
+				brandIds: [1, 2, 3],
+				accountIds: [],
+				isAdmin: false,
+				isSuperAdmin: false,
+				roles: [],
+			};
+			expect(hasAccessToBrand(user, 2)).toBe(true);
+		});
+
+		it("should return false if user does not have brand access", () => {
+			const user: User = {
+				username: "user",
+				email: "user@test.com",
+				brandIds: [1, 2, 3],
+				accountIds: [],
+				isAdmin: false,
+				isSuperAdmin: false,
+				roles: [],
+			};
+			expect(hasAccessToBrand(user, 5)).toBe(false);
+		});
+	});
+
+	describe("hasAccessToAccount", () => {
+		it("should return false for null user", () => {
+			expect(hasAccessToAccount(null, 1)).toBe(false);
+		});
+
+		it("should return true for admin user", () => {
+			const user: User = {
+				username: "admin",
+				email: "admin@test.com",
+				brandIds: [],
+				accountIds: [],
+				isAdmin: true,
+				isSuperAdmin: false,
+				roles: ["ADMINS"],
+			};
+			expect(hasAccessToAccount(user, 1)).toBe(true);
+		});
+
+		it("should return true if user has account access", () => {
+			const user: User = {
+				username: "user",
+				email: "user@test.com",
+				brandIds: [],
+				accountIds: [10, 20, 30],
+				isAdmin: false,
+				isSuperAdmin: false,
+				roles: [],
+			};
+			expect(hasAccessToAccount(user, 20)).toBe(true);
+		});
+
+		it("should return false if user does not have account access", () => {
+			const user: User = {
+				username: "user",
+				email: "user@test.com",
+				brandIds: [],
+				accountIds: [10, 20, 30],
+				isAdmin: false,
+				isSuperAdmin: false,
+				roles: [],
+			};
+			expect(hasAccessToAccount(user, 50)).toBe(false);
+		});
+	});
+
+	describe("isAdminUser", () => {
+		it("should return false for null user", () => {
+			expect(isAdminUser(null)).toBe(false);
+		});
+
+		it("should return true for admin user", () => {
+			const user: User = {
+				username: "admin",
+				email: "admin@test.com",
+				brandIds: [],
+				accountIds: [],
+				isAdmin: true,
+				isSuperAdmin: false,
+				roles: ["ADMINS"],
+			};
+			expect(isAdminUser(user)).toBe(true);
+		});
+
+		it("should return false for non-admin user", () => {
+			const user: User = {
+				username: "user",
+				email: "user@test.com",
+				brandIds: [],
+				accountIds: [],
+				isAdmin: false,
+				isSuperAdmin: false,
+				roles: [],
+			};
+			expect(isAdminUser(user)).toBe(false);
+		});
+	});
+
+	describe("isSuperAdminUser", () => {
+		it("should return false for null user", () => {
+			expect(isSuperAdminUser(null)).toBe(false);
+		});
+
+		it("should return true for super admin user", () => {
+			const user: User = {
+				username: "superadmin",
+				email: "superadmin@test.com",
+				brandIds: [],
+				accountIds: [],
+				isAdmin: true,
+				isSuperAdmin: true,
+				roles: ["SUPER_ADMINS"],
+			};
+			expect(isSuperAdminUser(user)).toBe(true);
+		});
+
+		it("should return false for regular admin user", () => {
+			const user: User = {
+				username: "admin",
+				email: "admin@test.com",
+				brandIds: [],
+				accountIds: [],
+				isAdmin: true,
+				isSuperAdmin: false,
+				roles: ["ADMINS"],
+			};
+			expect(isSuperAdminUser(user)).toBe(false);
+		});
+
+		it("should return false for non-admin user", () => {
+			const user: User = {
+				username: "user",
+				email: "user@test.com",
+				brandIds: [],
+				accountIds: [],
+				isAdmin: false,
+				isSuperAdmin: false,
+				roles: [],
+			};
+			expect(isSuperAdminUser(user)).toBe(false);
+		});
+	});
+
+	// Note: getClientUser tests are skipped because they require mocking AWS Amplify
+	// which is complex in a unit test environment. These should be tested in integration tests.
+});

package/src/auth/index.ts

@@ -0,0 +1,294 @@
+/**
+ * @htlkg/core/auth
+ * Core authentication functions and utilities
+ */
+
+import type { APIContext } from "astro";
+import { Amplify } from "aws-amplify";
+import { fetchAuthSession } from "aws-amplify/auth";
+import {
+	fetchAuthSession as fetchServerAuthSession,
+	getCurrentUser as getServerCurrentUser,
+} from "aws-amplify/auth/server";
+import { createRunWithAmplifyServerContext, globalSettings } from "../amplify-astro-adapter";
+
+// Re-export types
+export type { APIContext } from "astro";
+
+/**
+ * User interface representing an authenticated user
+ */
+export interface User {
+	username: string;
+	email: string;
+	brandIds: number[];
+	accountIds: number[];
+	isAdmin: boolean;
+	isSuperAdmin: boolean;
+	roles: string[];
+}
+
+/**
+ * Parse comma-separated IDs from Cognito custom attributes
+ */
+function parseIds(ids: string | undefined): number[] {
+	if (!ids) return [];
+	return ids
+		.split(",")
+		.map((id) => Number.parseInt(id.trim(), 10))
+		.filter((id) => !Number.isNaN(id));
+}
+
+// Track if Amplify has been configured
+let amplifyConfigured = false;
+
+/**
+ * Configure Amplify on first use (server-side)
+ * This must be called before any auth operations
+ */
+function ensureAmplifyConfigured(): void {
+	if (amplifyConfigured) return;
+
+	try {
+		// Amplify should already be configured by the middleware
+		// This is just a safety check
+		const config = Amplify.getConfig();
+		if (!config.Auth) {
+			throw new Error("Amplify Auth not configured");
+		}
+		amplifyConfigured = true;
+	} catch (error) {
+		const errorMsg = error instanceof Error ? error.message : "Unknown error";
+		console.error(`[Auth] Amplify not configured: ${errorMsg}`);
+		throw error;
+	}
+}
+
+/**
+ * Get current authenticated user (server-side)
+ * Reads Amplify auth cookies from the request and validates the session
+ */
+export async function getUser(context: APIContext): Promise<User | null> {
+	try {
+		ensureAmplifyConfigured();
+		
+		// Get the current Amplify configuration
+		const amplifyConfig = Amplify.getConfig();
+
+		// Create the server context runner - pass globalSettings explicitly
+		// to ensure the same instance is used across all modules
+		const runWithAmplifyServerContext = createRunWithAmplifyServerContext({
+			config: amplifyConfig,
+			globalSettings,
+		});
+
+		// Create Astro server context
+		const astroServerContext = {
+			cookies: context.cookies,
+			request: context.request,
+		};
+
+		// Run in Amplify server context
+		const user = await runWithAmplifyServerContext({
+			astroServerContext,
+			operation: async (contextSpec) => {
+				try {
+					const currentUser = await getServerCurrentUser(contextSpec as any);
+					const session = await fetchServerAuthSession(contextSpec as any);
+
+					if (!session.tokens?.accessToken) {
+						return null;
+					}
+
+					const accessPayload = session.tokens.accessToken.payload;
+					const idPayload = session.tokens.idToken?.payload;
+
+					// Parse user attributes - email is typically in ID token, not access token
+					const email =
+						(idPayload?.email as string) ||
+						(accessPayload.email as string) ||
+						"";
+					const brandIds = parseIds(
+						accessPayload["custom:brand_ids"] as string,
+					);
+					const accountIds = parseIds(
+						accessPayload["custom:account_ids"] as string,
+					);
+
+					// Check admin status
+					const groups = (accessPayload["cognito:groups"] as string[]) || [];
+					const isAdmin =
+						groups.includes("admin") ||
+						groups.includes("ADMINS") ||
+						groups.includes("SUPER_ADMINS");
+					const isSuperAdmin = groups.includes("SUPER_ADMINS");
+
+					return {
+						username: currentUser.username,
+						email,
+						brandIds,
+						accountIds,
+						isAdmin,
+						isSuperAdmin,
+						roles: groups,
+					};
+				} catch (error) {
+					// UserUnAuthenticatedException is expected when user is not logged in
+					// Only log other errors without sensitive data
+					if (
+						error instanceof Error &&
+						error.name !== "UserUnAuthenticatedException"
+					) {
+						// Log error name and message without stack trace or sensitive data
+						console.error(
+							"[Auth] Error in server context:",
+							error.name,
+							"-",
+							error.message.replace(/token[=:]\s*[^\s,}]+/gi, "token=***"),
+						);
+					}
+					return null;
+				}
+			},
+		});
+
+		return user;
+	} catch (error) {
+		// Log error without exposing sensitive information
+		if (error instanceof Error) {
+			console.error(
+				"[Auth] Server-side auth error:",
+				error.name,
+				"-",
+				error.message.replace(/token[=:]\s*[^\s,}]+/gi, "token=***"),
+			);
+		} else {
+			console.error("[Auth] Server-side auth error: Unknown error");
+		}
+		return null;
+	}
+}
+
+/**
+ * Get current authenticated user (client-side)
+ */
+export async function getClientUser(): Promise<User | null> {
+	try {
+		const session = await fetchAuthSession();
+
+		if (!session.tokens?.accessToken) {
+			return null;
+		}
+
+		const accessPayload = session.tokens.accessToken.payload;
+		const idPayload = session.tokens.idToken?.payload;
+
+		const email =
+			(idPayload?.email as string) || (accessPayload.email as string) || "";
+		const brandIds = parseIds(accessPayload["custom:brand_ids"] as string);
+		const accountIds = parseIds(accessPayload["custom:account_ids"] as string);
+
+		const groups = (accessPayload["cognito:groups"] as string[]) || [];
+		const isAdmin =
+			groups.includes("admin") ||
+			groups.includes("ADMINS") ||
+			groups.includes("SUPER_ADMINS");
+		const isSuperAdmin = groups.includes("SUPER_ADMINS");
+
+		return {
+			username: (accessPayload.username as string) || "",
+			email,
+			brandIds,
+			accountIds,
+			isAdmin,
+			isSuperAdmin,
+			roles: groups,
+		};
+	} catch (error) {
+		if (error instanceof Error) {
+			console.error(
+				"[Auth] Client auth error:",
+				error.name,
+				"-",
+				error.message.replace(/token[=:]\s*[^\s,}]+/gi, "token=***"),
+			);
+		}
+		return null;
+	}
+}
+
+/**
+ * Check if user has access to a specific brand
+ */
+export function hasAccessToBrand(
+	user: User | null,
+	brandId: number,
+): boolean {
+	if (!user) return false;
+	if (user.isAdmin) return true;
+	return user.brandIds.includes(brandId);
+}
+
+/**
+ * Check if user has access to a specific account
+ */
+export function hasAccessToAccount(
+	user: User | null,
+	accountId: number,
+): boolean {
+	if (!user) return false;
+	if (user.isAdmin) return true;
+	return user.accountIds.includes(accountId);
+}
+
+/**
+ * Check if user is an admin
+ */
+export function isAdminUser(user: User | null): boolean {
+	return user?.isAdmin || false;
+}
+
+/**
+ * Check if user is a super admin
+ */
+export function isSuperAdminUser(user: User | null): boolean {
+	return user?.isSuperAdmin || false;
+}
+
+/**
+ * Placeholder for requireAuth - will be implemented in @htlkg/integrations
+ * This is here for type exports and documentation
+ */
+export async function requireAuth(
+	context: APIContext,
+	loginUrl?: string,
+): Promise<{ success: boolean; user?: User; redirectTo?: string }> {
+	throw new Error(
+		"requireAuth should be imported from @htlkg/astro/middleware",
+	);
+}
+
+/**
+ * Placeholder for requireAdminAccess - will be implemented in @htlkg/integrations
+ */
+export async function requireAdminAccess(
+	context: APIContext,
+	loginUrl?: string,
+): Promise<{ success: boolean; user?: User; redirectTo?: string }> {
+	throw new Error(
+		"requireAdminAccess should be imported from @htlkg/astro/middleware",
+	);
+}
+
+/**
+ * Placeholder for requireBrandAccess - will be implemented in @htlkg/integrations
+ */
+export async function requireBrandAccess(
+	context: APIContext,
+	brandId: number,
+	loginUrl?: string,
+): Promise<{ success: boolean; user?: User; redirectTo?: string }> {
+	throw new Error(
+		"requireBrandAccess should be imported from @htlkg/astro/middleware",
+	);
+}

package/src/constants/constants.md

@@ -0,0 +1,132 @@
+# Constants Module
+
+Centralized constants for routes, products, permissions, and user roles.
+
+## Installation
+
+```typescript
+import { ROUTES, PRODUCTS, PERMISSIONS, USER_ROLES } from '@htlkg/core/constants';
+```
+
+## ROUTES
+
+Application route definitions.
+
+```typescript
+// Admin routes
+ROUTES.ADMIN.HOME        // "/admin"
+ROUTES.ADMIN.BRANDS      // "/admin/brands"
+ROUTES.ADMIN.ACCOUNTS    // "/admin/accounts"
+ROUTES.ADMIN.USERS       // "/admin/users"
+ROUTES.ADMIN.PRODUCTS    // "/admin/products"
+ROUTES.ADMIN.SETTINGS    // "/admin/settings"
+
+// Brand routes (with brandId parameter)
+ROUTES.BRAND.HOME(brandId)      // "/{brandId}"
+ROUTES.BRAND.ADMIN(brandId)     // "/{brandId}/admin"
+ROUTES.BRAND.TEMPLATES(brandId) // "/{brandId}/admin/templates"
+ROUTES.BRAND.SETTINGS(brandId)  // "/{brandId}/admin/settings"
+
+// Auth routes
+ROUTES.AUTH.LOGIN           // "/login"
+ROUTES.AUTH.LOGOUT          // "/logout"
+ROUTES.AUTH.SIGNUP          // "/signup"
+ROUTES.AUTH.FORGOT_PASSWORD // "/forgot-password"
+```
+
+## PRODUCTS
+
+Product definitions for the platform.
+
+```typescript
+PRODUCTS.WIFI_PORTAL
+// { id: "wifi-portal", name: "WiFi Portal", description: "..." }
+
+PRODUCTS.WHATSAPP_CRM
+// { id: "whatsapp-crm", name: "WhatsApp CRM", description: "..." }
+
+PRODUCTS.ANALYTICS
+// { id: "analytics", name: "Analytics", description: "..." }
+```
+
+## PERMISSIONS
+
+Permission string constants for authorization.
+
+```typescript
+// Brand permissions
+PERMISSIONS.BRAND_VIEW    // "brand:view"
+PERMISSIONS.BRAND_EDIT    // "brand:edit"
+PERMISSIONS.BRAND_DELETE  // "brand:delete"
+PERMISSIONS.BRAND_CREATE  // "brand:create"
+
+// Account permissions
+PERMISSIONS.ACCOUNT_VIEW   // "account:view"
+PERMISSIONS.ACCOUNT_EDIT   // "account:edit"
+PERMISSIONS.ACCOUNT_DELETE // "account:delete"
+PERMISSIONS.ACCOUNT_CREATE // "account:create"
+
+// User permissions
+PERMISSIONS.USER_VIEW   // "user:view"
+PERMISSIONS.USER_EDIT   // "user:edit"
+PERMISSIONS.USER_DELETE // "user:delete"
+PERMISSIONS.USER_CREATE // "user:create"
+
+// Product permissions
+PERMISSIONS.PRODUCT_VIEW    // "product:view"
+PERMISSIONS.PRODUCT_EDIT    // "product:edit"
+PERMISSIONS.PRODUCT_ENABLE  // "product:enable"
+PERMISSIONS.PRODUCT_DISABLE // "product:disable"
+
+// Admin permissions
+PERMISSIONS.ADMIN_ACCESS       // "admin:access"
+PERMISSIONS.SUPER_ADMIN_ACCESS // "super_admin:access"
+```
+
+## USER_ROLES
+
+Cognito group names for user roles.
+
+```typescript
+USER_ROLES.SUPER_ADMIN // "SUPER_ADMINS"
+USER_ROLES.ADMIN       // "ADMINS"
+USER_ROLES.BRAND_ADMIN // "BRAND_ADMINS"
+USER_ROLES.BRAND_USER  // "BRAND_USERS"
+USER_ROLES.USER        // "USERS"
+```
+
+## Usage Examples
+
+### Route Navigation
+
+```typescript
+import { ROUTES } from '@htlkg/core/constants';
+
+// Static routes
+window.location.href = ROUTES.AUTH.LOGIN;
+
+// Dynamic routes
+const brandId = '123';
+window.location.href = ROUTES.BRAND.ADMIN(brandId);
+```
+
+### Permission Checks
+
+```typescript
+import { PERMISSIONS } from '@htlkg/core/constants';
+
+function canEditBrand(userPermissions: string[]): boolean {
+  return userPermissions.includes(PERMISSIONS.BRAND_EDIT);
+}
+```
+
+### Role Checks
+
+```typescript
+import { USER_ROLES } from '@htlkg/core/constants';
+
+function isAdmin(userRoles: string[]): boolean {
+  return userRoles.includes(USER_ROLES.ADMIN) || 
+         userRoles.includes(USER_ROLES.SUPER_ADMIN);
+}
+```