@mandujs/core 0.5.4 → 0.5.6

package/src/filling/auth.ts

@@ -0,0 +1,308 @@
+/**
+ * Mandu Auth Guards - 인증/인가 헬퍼 🔐
+ *
+ * Guard에서 사용할 수 있는 타입-안전 인증 헬퍼
+ * 인증 실패 시 적절한 에러를 throw하여 Guard 체인 중단
+ */
+
+import type { ManduContext } from "./context";
+
+/**
+ * 인증 실패 에러 (401 Unauthorized)
+ */
+export class AuthenticationError extends Error {
+  readonly statusCode = 401;
+
+  constructor(message: string = "Authentication required") {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+}
+
+/**
+ * 인가 실패 에러 (403 Forbidden)
+ */
+export class AuthorizationError extends Error {
+  readonly statusCode = 403;
+  readonly requiredRoles?: string[];
+
+  constructor(message: string = "Access denied", requiredRoles?: string[]) {
+    super(message);
+    this.name = "AuthorizationError";
+    this.requiredRoles = requiredRoles;
+  }
+}
+
+/**
+ * 기본 User 인터페이스
+ * 프로젝트에서 확장하여 사용
+ */
+export interface BaseUser {
+  id: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Role을 가진 User 인터페이스
+ */
+export interface UserWithRole extends BaseUser {
+  role: string;
+}
+
+/**
+ * Roles 배열을 가진 User 인터페이스
+ */
+export interface UserWithRoles extends BaseUser {
+  roles: string[];
+}
+
+// ============================================
+// 🔐 Auth Guard Helpers
+// ============================================
+
+/**
+ * 인증된 사용자 필수
+ * Guard에서 user가 없으면 AuthenticationError throw
+ *
+ * @param ctx ManduContext
+ * @param key store에서 user를 찾을 키 (기본: 'user')
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError
+ *
+ * @example
+ * ```typescript
+ * import { requireUser } from '@mandujs/core'
+ *
+ * export default Mandu.filling()
+ *   .guard(async (ctx) => {
+ *     // JWT 토큰 검증 후 user 저장
+ *     const user = await verifyToken(ctx.headers.get('Authorization'));
+ *     ctx.set('user', user);
+ *     return ctx.next();
+ *   })
+ *   .get((ctx) => {
+ *     const user = requireUser(ctx);  // User 타입 확정, 없으면 401
+ *     return ctx.ok({ message: `Hello, ${user.id}!` });
+ *   })
+ * ```
+ */
+export function requireUser<T extends BaseUser = BaseUser>(
+  ctx: ManduContext,
+  key: string = "user"
+): T {
+  const user = ctx.get<T>(key);
+
+  if (!user) {
+    throw new AuthenticationError("User context is required");
+  }
+
+  if (typeof user !== "object" || !("id" in user)) {
+    throw new AuthenticationError("Invalid user context");
+  }
+
+  return user;
+}
+
+/**
+ * 특정 역할 필수 (단일 role 필드)
+ *
+ * @param ctx ManduContext
+ * @param roles 허용된 역할 목록
+ * @param key store에서 user를 찾을 키 (기본: 'user')
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError (user 없음)
+ * @throws AuthorizationError (역할 불일치)
+ *
+ * @example
+ * ```typescript
+ * .guard((ctx) => {
+ *   requireRole(ctx, 'admin', 'moderator');  // admin 또는 moderator만 허용
+ *   return ctx.next();
+ * })
+ * ```
+ */
+export function requireRole<T extends UserWithRole = UserWithRole>(
+  ctx: ManduContext,
+  ...roles: string[]
+): T {
+  const user = requireUser<T>(ctx);
+
+  if (!("role" in user) || typeof user.role !== "string") {
+    throw new AuthorizationError("User has no role defined");
+  }
+
+  if (!roles.includes(user.role)) {
+    throw new AuthorizationError(
+      `Required role: ${roles.join(" or ")}`,
+      roles
+    );
+  }
+
+  return user;
+}
+
+/**
+ * 특정 역할 중 하나 필수 (roles 배열 필드)
+ *
+ * @param ctx ManduContext
+ * @param roles 허용된 역할 목록 (하나라도 있으면 통과)
+ * @param key store에서 user를 찾을 키 (기본: 'user')
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError (user 없음)
+ * @throws AuthorizationError (역할 불일치)
+ *
+ * @example
+ * ```typescript
+ * .guard((ctx) => {
+ *   requireAnyRole(ctx, 'editor', 'admin');  // editor 또는 admin 역할 필요
+ *   return ctx.next();
+ * })
+ * ```
+ */
+export function requireAnyRole<T extends UserWithRoles = UserWithRoles>(
+  ctx: ManduContext,
+  ...roles: string[]
+): T {
+  const user = requireUser<T>(ctx);
+
+  if (!("roles" in user) || !Array.isArray(user.roles)) {
+    throw new AuthorizationError("User has no roles defined");
+  }
+
+  const hasRole = roles.some((role) => user.roles.includes(role));
+
+  if (!hasRole) {
+    throw new AuthorizationError(
+      `Required one of roles: ${roles.join(", ")}`,
+      roles
+    );
+  }
+
+  return user;
+}
+
+/**
+ * 모든 역할 필수 (roles 배열 필드)
+ *
+ * @param ctx ManduContext
+ * @param roles 필요한 역할 목록 (모두 있어야 통과)
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError (user 없음)
+ * @throws AuthorizationError (역할 불일치)
+ *
+ * @example
+ * ```typescript
+ * .guard((ctx) => {
+ *   requireAllRoles(ctx, 'verified', 'premium');  // verified AND premium 필요
+ *   return ctx.next();
+ * })
+ * ```
+ */
+export function requireAllRoles<T extends UserWithRoles = UserWithRoles>(
+  ctx: ManduContext,
+  ...roles: string[]
+): T {
+  const user = requireUser<T>(ctx);
+
+  if (!("roles" in user) || !Array.isArray(user.roles)) {
+    throw new AuthorizationError("User has no roles defined");
+  }
+
+  const missingRoles = roles.filter((role) => !user.roles.includes(role));
+
+  if (missingRoles.length > 0) {
+    throw new AuthorizationError(
+      `Missing required roles: ${missingRoles.join(", ")}`,
+      roles
+    );
+  }
+
+  return user;
+}
+
+// ============================================
+// 🔐 Auth Guard Factory
+// ============================================
+
+/**
+ * 인증 Guard 생성 팩토리
+ * 반복되는 인증 로직을 Guard로 변환
+ *
+ * @example
+ * ```typescript
+ * const authGuard = createAuthGuard(async (ctx) => {
+ *   const token = ctx.headers.get('Authorization')?.replace('Bearer ', '');
+ *   if (!token) return null;
+ *   return await verifyJwt(token);
+ * });
+ *
+ * export default Mandu.filling()
+ *   .guard(authGuard)
+ *   .get((ctx) => {
+ *     const user = requireUser(ctx);
+ *     return ctx.ok({ user });
+ *   })
+ * ```
+ */
+export function createAuthGuard<T extends BaseUser>(
+  authenticator: (ctx: ManduContext) => T | null | Promise<T | null>,
+  options: {
+    key?: string;
+    onUnauthenticated?: (ctx: ManduContext) => Response;
+  } = {}
+) {
+  const { key = "user", onUnauthenticated } = options;
+
+  return async (ctx: ManduContext): Promise<symbol | Response> => {
+    try {
+      const user = await authenticator(ctx);
+
+      if (user) {
+        ctx.set(key, user);
+        return ctx.next();
+      }
+
+      if (onUnauthenticated) {
+        return onUnauthenticated(ctx);
+      }
+
+      return ctx.unauthorized("Authentication required");
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        return ctx.unauthorized(error.message);
+      }
+      throw error;
+    }
+  };
+}
+
+/**
+ * 역할 기반 Guard 생성 팩토리
+ *
+ * @example
+ * ```typescript
+ * const adminOnly = createRoleGuard('admin');
+ * const editorOrAdmin = createRoleGuard('editor', 'admin');
+ *
+ * export default Mandu.filling()
+ *   .guard(authGuard)
+ *   .guard(adminOnly)  // admin만 접근 가능
+ *   .delete((ctx) => ctx.noContent())
+ * ```
+ */
+export function createRoleGuard(...allowedRoles: string[]) {
+  return (ctx: ManduContext): symbol | Response => {
+    try {
+      requireRole(ctx, ...allowedRoles);
+      return ctx.next();
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        return ctx.unauthorized(error.message);
+      }
+      if (error instanceof AuthorizationError) {
+        return ctx.forbidden(error.message);
+      }
+      throw error;
+    }
+  };
+}

package/src/filling/context.ts

@@ -49,7 +49,13 @@ export class CookieManager {
       for (const pair of pairs) {
         const [name, ...rest] = pair.trim().split("=");
         if (name) {
-          cookies.set(name, decodeURIComponent(rest.join("=")));
+          const rawValue = rest.join("=");
+          try {
+            cookies.set(name, decodeURIComponent(rawValue));
+          } catch {
+            // 잘못된 URL 인코딩 시 원본 값 사용
+            cookies.set(name, rawValue);
+          }
         }
       }
     }

package/src/filling/filling.ts

@@ -4,6 +4,7 @@
  */
 
 import { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
+import { AuthenticationError, AuthorizationError } from "./auth";
 import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
 import { createContract, type ContractDefinition, type ContractInstance } from "../contract";
 
@@ -19,6 +20,22 @@ export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" |
 /** Loader function type - SSR 데이터 로딩 */
 export type Loader<T = unknown> = (ctx: ManduContext) => T | Promise<T>;
 
+/** Loader 실행 옵션 */
+export interface LoaderOptions<T = unknown> {
+  /** 타임아웃 (ms), 기본값 5000 */
+  timeout?: number;
+  /** 타임아웃 또는 에러 시 반환할 fallback 데이터 */
+  fallback?: T;
+}
+
+/** Loader 타임아웃 에러 */
+export class LoaderTimeoutError extends Error {
+  constructor(timeout: number) {
+    super(`Loader timed out after ${timeout}ms`);
+    this.name = "LoaderTimeoutError";
+  }
+}
+
 interface FillingConfig<TLoaderData = unknown> {
   handlers: Map<HttpMethod, Handler>;
   guards: Guard[];
@@ -78,12 +95,37 @@ export class ManduFilling<TLoaderData = unknown> {
   /**
    * Execute loader and return data
    * @internal Used by SSR runtime
+   * @param ctx ManduContext
+   * @param options Loader 실행 옵션 (timeout, fallback)
    */
-  async executeLoader(ctx: ManduContext): Promise<TLoaderData | undefined> {
+  async executeLoader(
+    ctx: ManduContext,
+    options: LoaderOptions<TLoaderData> = {}
+  ): Promise<TLoaderData | undefined> {
     if (!this.config.loader) {
       return undefined;
     }
-    return await this.config.loader(ctx);
+
+    const { timeout = 5000, fallback } = options;
+
+    try {
+      const loaderPromise = Promise.resolve(this.config.loader(ctx));
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new LoaderTimeoutError(timeout)), timeout);
+      });
+
+      return await Promise.race([loaderPromise, timeoutPromise]);
+    } catch (error) {
+      if (fallback !== undefined) {
+        console.warn(
+          `[Mandu] Loader failed, using fallback:`,
+          error instanceof Error ? error.message : String(error)
+        );
+        return fallback;
+      }
+      throw error;
+    }
   }
 
   /**
@@ -203,7 +245,11 @@ export class ManduFilling<TLoaderData = unknown> {
           return result as Response;
         }
         if (!ctx.shouldContinue) {
-          return ctx.getResponse()!;
+          const response = ctx.getResponse();
+          if (!response) {
+            throw new Error("Guard set shouldContinue=false but no response was provided");
+          }
+          return response;
         }
       }
 
@@ -215,7 +261,11 @@ export class ManduFilling<TLoaderData = unknown> {
           return result as Response;
         }
         if (!ctx.shouldContinue) {
-          return ctx.getResponse()!;
+          const response = ctx.getResponse();
+          if (!response) {
+            throw new Error("Guard set shouldContinue=false but no response was provided");
+          }
+          return response;
         }
       }
 
@@ -235,6 +285,35 @@ export class ManduFilling<TLoaderData = unknown> {
       // Execute handler
       return await handler(ctx);
     } catch (error) {
+      // Handle authentication errors
+      if (error instanceof AuthenticationError) {
+        return ctx.json(
+          {
+            errorType: "AUTH_ERROR",
+            code: "AUTHENTICATION_REQUIRED",
+            message: error.message,
+            summary: "인증 필요 - 로그인 후 다시 시도하세요",
+            timestamp: new Date().toISOString(),
+          },
+          401
+        );
+      }
+
+      // Handle authorization errors
+      if (error instanceof AuthorizationError) {
+        return ctx.json(
+          {
+            errorType: "AUTH_ERROR",
+            code: "ACCESS_DENIED",
+            message: error.message,
+            summary: "권한 없음 - 접근 권한이 부족합니다",
+            requiredRoles: error.requiredRoles,
+            timestamp: new Date().toISOString(),
+          },
+          403
+        );
+      }
+
       // Handle validation errors with enhanced error format
       if (error instanceof ValidationError) {
         return ctx.json(

package/src/filling/index.ts

@@ -4,5 +4,18 @@
 
 export { ManduContext, NEXT_SYMBOL, ValidationError, CookieManager } from "./context";
 export type { CookieOptions } from "./context";
-export { ManduFilling, Mandu } from "./filling";
-export type { Handler, Guard, HttpMethod } from "./filling";
+export { ManduFilling, Mandu, LoaderTimeoutError } from "./filling";
+export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
+
+// Auth Guards
+export {
+  AuthenticationError,
+  AuthorizationError,
+  requireUser,
+  requireRole,
+  requireAnyRole,
+  requireAllRoles,
+  createAuthGuard,
+  createRoleGuard,
+} from "./auth";
+export type { BaseUser, UserWithRole, UserWithRoles } from "./auth";

package/src/generator/generate.ts

@@ -20,6 +20,8 @@ export interface GenerateResult {
   deleted: string[];
   skipped: string[];
   errors: string[];
+  /** 삭제 실패 등 치명적이지 않은 경고 */
+  warnings: string[];
 }
 
 /**
@@ -130,6 +132,7 @@ export async function generateRoutes(
     deleted: [],
     skipped: [],
     errors: [],
+    warnings: [],
   };
 
   const serverRoutesDir = path.join(rootDir, "apps/server/generated/routes");
@@ -289,8 +292,14 @@ export async function generateRoutes(
   for (const file of existingServerFiles) {
     if (!expectedServerFiles.has(file)) {
       const filePath = path.join(serverRoutesDir, file);
-      await fs.unlink(filePath);
-      result.deleted.push(filePath);
+      try {
+        await fs.unlink(filePath);
+        result.deleted.push(filePath);
+      } catch (error) {
+        result.warnings.push(
+          `Failed to delete ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
   }
 
@@ -298,8 +307,14 @@ export async function generateRoutes(
   for (const file of existingWebFiles) {
     if (!expectedWebFiles.has(file)) {
       const filePath = path.join(webRoutesDir, file);
-      await fs.unlink(filePath);
-      result.deleted.push(filePath);
+      try {
+        await fs.unlink(filePath);
+        result.deleted.push(filePath);
+      } catch (error) {
+        result.warnings.push(
+          `Failed to delete ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
   }
 
@@ -308,8 +323,14 @@ export async function generateRoutes(
   for (const file of existingTypeFiles) {
     if (!expectedTypeFiles.has(file) && file !== "index.ts") {
       const filePath = path.join(typesDir, file);
-      await fs.unlink(filePath);
-      result.deleted.push(filePath);
+      try {
+        await fs.unlink(filePath);
+        result.deleted.push(filePath);
+      } catch (error) {
+        result.warnings.push(
+          `Failed to delete ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
   }
 

package/src/generator/index.ts

@@ -1,3 +1,3 @@
-export * from "./generate";
-export * from "./templates";
-export * from "./contract-glue";
+export * from "./generate";
+export * from "./templates";
+export * from "./contract-glue";

package/src/report/index.ts

@@ -1 +1 @@
-export * from "./build";
+export * from "./build";

package/src/runtime/index.ts

@@ -1,5 +1,5 @@
-export * from "./ssr";
-export * from "./router";
-export * from "./server";
-export * from "./cors";
-export * from "./env";
+export * from "./ssr";
+export * from "./router";
+export * from "./server";
+export * from "./cors";
+export * from "./env";