@htlkg/core 0.0.1 → 0.0.3

package/src/auth/auth.md

@@ -0,0 +1,178 @@
+# Auth Module
+
+Core authentication functions for server-side and client-side user management with AWS Cognito.
+
+## Installation
+
+```typescript
+import { 
+  getUser, 
+  getClientUser,
+  hasAccessToBrand,
+  hasAccessToAccount,
+  isAdminUser,
+  isSuperAdminUser,
+} from '@htlkg/core/auth';
+```
+
+## User Interface
+
+```typescript
+interface User {
+  username: string;
+  email: string;
+  brandIds: number[];
+  accountIds: number[];
+  isAdmin: boolean;
+  isSuperAdmin: boolean;
+  roles: string[];
+}
+```
+
+## Server-Side Authentication
+
+### getUser
+
+Retrieves the authenticated user from Astro's API context using Cognito cookies.
+
+```typescript
+import type { APIContext } from 'astro';
+import { getUser } from '@htlkg/core/auth';
+
+export async function GET(context: APIContext) {
+  const user = await getUser(context);
+  
+  if (!user) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+  
+  return new Response(JSON.stringify(user));
+}
+```
+
+In Astro pages:
+
+```astro
+---
+import { getUser } from '@htlkg/core/auth';
+
+const user = await getUser(Astro);
+
+if (!user) {
+  return Astro.redirect('/login');
+}
+---
+
+<h1>Welcome, {user.username}</h1>
+```
+
+## Client-Side Authentication
+
+### getClientUser
+
+Retrieves the authenticated user on the client side.
+
+```typescript
+import { getClientUser } from '@htlkg/core/auth';
+
+const user = await getClientUser();
+
+if (user) {
+  console.log(`Logged in as ${user.email}`);
+}
+```
+
+## Access Control Helpers
+
+### hasAccessToBrand
+
+Check if user has access to a specific brand.
+
+```typescript
+import { getUser, hasAccessToBrand } from '@htlkg/core/auth';
+
+const user = await getUser(context);
+const brandId = 123;
+
+if (!hasAccessToBrand(user, brandId)) {
+  return new Response('Forbidden', { status: 403 });
+}
+```
+
+### hasAccessToAccount
+
+Check if user has access to a specific account.
+
+```typescript
+import { getUser, hasAccessToAccount } from '@htlkg/core/auth';
+
+const user = await getUser(context);
+
+if (hasAccessToAccount(user, accountId)) {
+  // User can access this account
+}
+```
+
+### isAdminUser / isSuperAdminUser
+
+Check admin status.
+
+```typescript
+import { getUser, isAdminUser, isSuperAdminUser } from '@htlkg/core/auth';
+
+const user = await getUser(context);
+
+if (isAdminUser(user)) {
+  // User is admin or super admin
+}
+
+if (isSuperAdminUser(user)) {
+  // User is super admin only
+}
+```
+
+## Cognito Groups
+
+The module recognizes these Cognito groups:
+
+| Group | Admin | Super Admin |
+|-------|-------|-------------|
+| `admin` | ✓ | ✗ |
+| `ADMINS` | ✓ | ✗ |
+| `SUPER_ADMINS` | ✓ | ✓ |
+
+## Custom Attributes
+
+User attributes are parsed from Cognito tokens:
+
+- `custom:brand_ids` - Comma-separated brand IDs
+- `custom:account_ids` - Comma-separated account IDs
+- `email` - From ID token
+- `cognito:groups` - User roles/groups
+
+## Error Handling
+
+Authentication errors are logged without exposing sensitive data:
+
+```typescript
+const user = await getUser(context);
+// Returns null on any auth error
+// Errors logged with sanitized messages (tokens masked)
+```
+
+## Middleware Placeholders
+
+These functions are placeholders that should be imported from `@htlkg/astro/middleware`:
+
+```typescript
+// These throw errors if called directly from @htlkg/core
+requireAuth(context, loginUrl);
+requireAdminAccess(context, loginUrl);
+requireBrandAccess(context, brandId, loginUrl);
+```
+
+Import from the correct package:
+
+```typescript
+import { requireAuth } from '@htlkg/astro/middleware';
+```

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",
+	);
+}