@mandujs/mcp 0.9.19 → 0.9.21

package/src/resources/skills/mandu-security/rules/sec-input-validate.md

@@ -0,0 +1,148 @@
+---
+title: Always Validate and Sanitize Input
+impact: CRITICAL
+impactDescription: Prevents injection attacks
+tags: security, input, validation, sanitize
+---
+
+## Always Validate and Sanitize Input
+
+**Impact: CRITICAL (Prevents injection attacks)**
+
+모든 사용자 입력을 서버에서 검증하고 살균하세요. 클라이언트 검증은 우회될 수 있습니다.
+
+**Vulnerable (검증 없음):**
+
+```typescript
+// ❌ 입력 검증 없이 직접 사용
+export default Mandu.filling()
+  .post(async (ctx) => {
+    const body = await ctx.body();
+
+    // SQL Injection 취약
+    const user = await db.$queryRaw`
+      SELECT * FROM users WHERE email = '${body.email}'
+    `;
+
+    return ctx.ok({ user });
+  });
+```
+
+**Secure (Zod로 검증):**
+
+```typescript
+import { z } from "zod";
+
+// ✅ 스키마 정의
+const createUserSchema = z.object({
+  email: z.string().email().max(255),
+  name: z.string().min(1).max(100),
+  age: z.number().int().min(0).max(150).optional(),
+});
+
+export default Mandu.filling()
+  .post(async (ctx) => {
+    const body = await ctx.body();
+
+    // 스키마로 검증
+    const result = createUserSchema.safeParse(body);
+
+    if (!result.success) {
+      return ctx.error({
+        message: "Validation failed",
+        errors: result.error.flatten(),
+      });
+    }
+
+    // 검증된 데이터 사용 (Parameterized query)
+    const user = await db.user.create({
+      data: result.data,
+    });
+
+    return ctx.created({ user });
+  });
+```
+
+## 입력 유형별 검증
+
+```typescript
+const schema = z.object({
+  // 문자열
+  username: z.string()
+    .min(3)
+    .max(20)
+    .regex(/^[a-zA-Z0-9_]+$/),  // 알파벳, 숫자, 언더스코어만
+
+  // 이메일
+  email: z.string().email(),
+
+  // URL
+  website: z.string().url().optional(),
+
+  // 숫자
+  age: z.number().int().positive().max(150),
+
+  // Enum
+  role: z.enum(["user", "admin", "moderator"]),
+
+  // 배열
+  tags: z.array(z.string().max(50)).max(10),
+
+  // 중첩 객체
+  address: z.object({
+    street: z.string().max(200),
+    city: z.string().max(100),
+  }).optional(),
+});
+```
+
+## 파일 업로드 검증
+
+```typescript
+export default Mandu.filling()
+  .post(async (ctx) => {
+    const formData = await ctx.req.formData();
+    const file = formData.get("file") as File;
+
+    // 파일 존재 확인
+    if (!file) {
+      return ctx.error("File is required");
+    }
+
+    // 파일 크기 제한 (5MB)
+    if (file.size > 5 * 1024 * 1024) {
+      return ctx.error("File too large (max 5MB)");
+    }
+
+    // 파일 타입 확인
+    const allowedTypes = ["image/jpeg", "image/png", "image/webp"];
+    if (!allowedTypes.includes(file.type)) {
+      return ctx.error("Invalid file type");
+    }
+
+    // 파일 확장자 확인 (MIME 스푸핑 방지)
+    const ext = file.name.split(".").pop()?.toLowerCase();
+    if (!["jpg", "jpeg", "png", "webp"].includes(ext || "")) {
+      return ctx.error("Invalid file extension");
+    }
+
+    // 안전하게 처리
+    const buffer = await file.arrayBuffer();
+    // ... 저장 로직
+  });
+```
+
+## XSS 방지를 위한 출력 이스케이프
+
+```typescript
+import { escapeHtml } from "@/lib/security";
+
+// HTML 컨텍스트에서 사용될 데이터
+const safeContent = escapeHtml(userInput);
+
+// 또는 라이브러리 사용
+import DOMPurify from "isomorphic-dompurify";
+const sanitized = DOMPurify.sanitize(userHtml);
+```
+
+Reference: [OWASP Input Validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html)

package/src/resources/skills/mandu-security/rules/sec-protect-csrf.md

@@ -0,0 +1,146 @@
+---
+title: Implement CSRF Protection
+impact: HIGH
+impactDescription: Prevents cross-site request forgery
+tags: security, csrf, protection, token
+---
+
+## Implement CSRF Protection
+
+**Impact: HIGH (Prevents cross-site request forgery)**
+
+상태를 변경하는 요청(POST, PUT, DELETE)에 CSRF 토큰을 적용하세요.
+
+**Vulnerable (CSRF 보호 없음):**
+
+```typescript
+// ❌ CSRF 토큰 없이 상태 변경
+export default Mandu.filling()
+  .post(async (ctx) => {
+    // 악의적인 사이트에서 이 요청을 보낼 수 있음
+    await db.user.delete({
+      where: { id: ctx.get("user").id },
+    });
+    return ctx.ok({ message: "Account deleted" });
+  });
+```
+
+**Secure (CSRF 토큰 검증):**
+
+```typescript
+import { verifyCsrfToken } from "@/lib/csrf";
+
+export default Mandu.filling()
+  .guard((ctx) => {
+    const user = ctx.get("user");
+    if (!user) return ctx.unauthorized();
+
+    // CSRF 토큰 검증
+    const token = ctx.headers.get("x-csrf-token");
+    if (!verifyCsrfToken(token, user.sessionId)) {
+      return ctx.forbidden("Invalid CSRF token");
+    }
+  })
+  .post(async (ctx) => {
+    await db.user.delete({
+      where: { id: ctx.get("user").id },
+    });
+    return ctx.ok({ message: "Account deleted" });
+  });
+```
+
+## CSRF 토큰 생성
+
+```typescript
+// lib/csrf.ts
+import { createHmac, randomBytes } from "crypto";
+
+const SECRET = process.env.CSRF_SECRET!;
+
+export function generateCsrfToken(sessionId: string): string {
+  const timestamp = Date.now().toString();
+  const random = randomBytes(16).toString("hex");
+  const data = `${sessionId}:${timestamp}:${random}`;
+
+  const signature = createHmac("sha256", SECRET)
+    .update(data)
+    .digest("hex");
+
+  return `${data}:${signature}`;
+}
+
+export function verifyCsrfToken(token: string | null, sessionId: string): boolean {
+  if (!token) return false;
+
+  const parts = token.split(":");
+  if (parts.length !== 4) return false;
+
+  const [tokenSessionId, timestamp, random, signature] = parts;
+
+  // 세션 ID 확인
+  if (tokenSessionId !== sessionId) return false;
+
+  // 만료 확인 (1시간)
+  const tokenTime = parseInt(timestamp, 10);
+  if (Date.now() - tokenTime > 3600000) return false;
+
+  // 서명 확인
+  const data = `${tokenSessionId}:${timestamp}:${random}`;
+  const expectedSignature = createHmac("sha256", SECRET)
+    .update(data)
+    .digest("hex");
+
+  return signature === expectedSignature;
+}
+```
+
+## 클라이언트에서 CSRF 토큰 전송
+
+```tsx
+// Island에서 CSRF 토큰 사용
+"use client";
+
+export function DeleteAccountButton({ csrfToken }: { csrfToken: string }) {
+  const handleDelete = async () => {
+    const res = await fetch("/api/account", {
+      method: "DELETE",
+      headers: {
+        "Content-Type": "application/json",
+        "X-CSRF-Token": csrfToken,  // CSRF 토큰 포함
+      },
+    });
+
+    if (res.ok) {
+      window.location.href = "/goodbye";
+    }
+  };
+
+  return <button onClick={handleDelete}>Delete Account</button>;
+}
+```
+
+## SameSite 쿠키와 함께 사용
+
+```typescript
+// 세션 쿠키 설정
+ctx.cookie("session", sessionId, {
+  httpOnly: true,
+  secure: true,
+  sameSite: "lax",  // 또는 "strict"
+  maxAge: 86400,
+});
+```
+
+## 추가 방어 (Double Submit)
+
+```typescript
+// 쿠키와 헤더 모두에서 토큰 확인
+const cookieToken = ctx.cookies.get("csrf");
+const headerToken = ctx.headers.get("x-csrf-token");
+
+if (!cookieToken || cookieToken !== headerToken) {
+  return ctx.forbidden("CSRF validation failed");
+}
+```
+
+Reference: [OWASP CSRF Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)

package/src/resources/skills/mandu-security/rules/sec-protect-headers.md

@@ -0,0 +1,138 @@
+---
+title: Configure Security Headers
+impact: HIGH
+impactDescription: Enables browser security features
+tags: security, headers, csp, hsts
+---
+
+## Configure Security Headers
+
+**Impact: HIGH (Enables browser security features)**
+
+보안 헤더를 설정하여 브라우저의 보안 기능을 활성화하세요.
+
+**기본 보안 헤더 설정:**
+
+```typescript
+// middleware/security.ts
+export function securityHeaders(ctx: Context) {
+  // XSS 필터 활성화
+  ctx.header("X-XSS-Protection", "1; mode=block");
+
+  // MIME 타입 스니핑 방지
+  ctx.header("X-Content-Type-Options", "nosniff");
+
+  // Clickjacking 방지
+  ctx.header("X-Frame-Options", "DENY");
+
+  // Referrer 정보 제한
+  ctx.header("Referrer-Policy", "strict-origin-when-cross-origin");
+
+  // HTTPS 강제 (프로덕션)
+  if (process.env.NODE_ENV === "production") {
+    ctx.header("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+  }
+}
+```
+
+## Content Security Policy (CSP)
+
+```typescript
+// 엄격한 CSP 설정
+const csp = [
+  "default-src 'self'",
+  "script-src 'self' 'unsafe-inline'",  // Island hydration 필요
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: https:",
+  "font-src 'self'",
+  "connect-src 'self' https://api.example.com",
+  "frame-ancestors 'none'",
+  "base-uri 'self'",
+  "form-action 'self'",
+].join("; ");
+
+ctx.header("Content-Security-Policy", csp);
+```
+
+## Nonce 기반 CSP (더 안전)
+
+```typescript
+// 요청마다 새 nonce 생성
+import { randomBytes } from "crypto";
+
+export function createCspNonce(): string {
+  return randomBytes(16).toString("base64");
+}
+
+// 미들웨어에서 설정
+const nonce = createCspNonce();
+ctx.set("cspNonce", nonce);
+
+const csp = [
+  "default-src 'self'",
+  `script-src 'self' 'nonce-${nonce}'`,  // nonce가 있는 스크립트만 허용
+  "style-src 'self' 'unsafe-inline'",
+  // ...
+].join("; ");
+
+ctx.header("Content-Security-Policy", csp);
+```
+
+```html
+<!-- HTML에서 nonce 사용 -->
+<script nonce="${nonce}">
+  // 이 스크립트만 실행됨
+</script>
+```
+
+## Permissions Policy
+
+```typescript
+// 브라우저 기능 제한
+const permissions = [
+  "camera=()",           // 카메라 비활성화
+  "microphone=()",       // 마이크 비활성화
+  "geolocation=(self)",  // 지오로케이션은 자체 도메인만
+  "payment=(self)",      // 결제는 자체 도메인만
+].join(", ");
+
+ctx.header("Permissions-Policy", permissions);
+```
+
+## 전체 보안 헤더 미들웨어
+
+```typescript
+// middleware/security.ts
+export function applySecurityHeaders(ctx: Context) {
+  const headers = {
+    "X-XSS-Protection": "1; mode=block",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "Permissions-Policy": "camera=(), microphone=(), geolocation=(self)",
+  };
+
+  // 프로덕션 전용
+  if (process.env.NODE_ENV === "production") {
+    headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains; preload";
+    headers["Content-Security-Policy"] = buildCsp();
+  }
+
+  Object.entries(headers).forEach(([key, value]) => {
+    ctx.header(key, value);
+  });
+}
+```
+
+## 검증 도구
+
+```bash
+# 헤더 확인
+curl -I https://your-site.com
+
+# 보안 헤더 스캔
+# https://securityheaders.com
+# https://observatory.mozilla.org
+```
+
+Reference: [OWASP Secure Headers](https://owasp.org/www-project-secure-headers/)

package/src/resources/skills/mandu-slot/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: mandu-slot
+description: |
+  Mandu Slot API for writing business logic. Use when creating API handlers,
+  implementing authentication guards, adding lifecycle hooks, or working with
+  request/response context. Triggers on tasks involving Mandu.filling(),
+  ctx.ok(), ctx.error(), .guard(), .get(), .post(), or slot files.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu Slot
+
+Slot은 비즈니스 로직을 작성하는 파일입니다. `Mandu.filling()` API를 사용하여
+API 핸들러, 인증 가드, 라이프사이클 훅을 구현합니다.
+
+## When to Apply
+
+Reference these guidelines when:
+- Creating new API endpoints with business logic
+- Implementing authentication or authorization
+- Adding request/response lifecycle hooks
+- Working with request body, params, or query
+- Handling errors and responses
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Basic Structure | CRITICAL | `slot-basic-` |
+| 2 | HTTP Methods | HIGH | `slot-http-` |
+| 3 | Context API | HIGH | `slot-ctx-` |
+| 4 | Guard Pattern | MEDIUM | `slot-guard-` |
+| 5 | Lifecycle Hooks | MEDIUM | `slot-lifecycle-` |
+
+## Quick Reference
+
+### 1. Basic Structure (CRITICAL)
+
+- `slot-basic-structure` - Always use Mandu.filling() as default export
+- `slot-basic-location` - Place slot files in spec/slots/ directory
+
+### 2. HTTP Methods (HIGH)
+
+- `slot-http-get` - Use .get() for read operations
+- `slot-http-post` - Use .post() for create operations
+- `slot-http-put-patch` - Use .put()/.patch() for updates
+- `slot-http-delete` - Use .delete() for removal
+
+### 3. Context API (HIGH)
+
+- `slot-ctx-response` - Use ctx.ok(), ctx.created(), ctx.error() for responses
+- `slot-ctx-body` - Use ctx.body<T>() for typed request body
+- `slot-ctx-params` - Use ctx.params for route parameters
+- `slot-ctx-state` - Use ctx.set()/ctx.get() for request state
+
+### 4. Guard Pattern (MEDIUM)
+
+- `slot-guard-auth` - Use .guard() for authentication checks
+- `slot-guard-early-return` - Return response to block, void to continue
+
+### 5. Lifecycle Hooks (MEDIUM)
+
+- `slot-lifecycle-request` - Use .onRequest() for request initialization
+- `slot-lifecycle-after` - Use .afterHandle() for response modification
+- `slot-lifecycle-middleware` - Use .middleware() for Koa-style chains
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/slot-basic-structure.md
+rules/slot-ctx-response.md
+rules/slot-guard-auth.md
+```
+
+## File Location
+
+```
+spec/slots/{name}.slot.ts    # Server logic
+spec/slots/{name}.client.ts  # Client logic (Island)
+```

package/src/resources/skills/mandu-slot/metadata.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "February 2026",
+  "abstract": "Mandu Slot API를 사용한 비즈니스 로직 작성 가이드. Mandu.filling()을 통한 HTTP 핸들러 정의, ctx 응답 메서드, guard 인증, 라이프사이클 훅을 다룹니다. 4개 카테고리의 규칙으로 구성되어 있으며, 에이전트가 올바른 slot 코드를 생성할 수 있도록 안내합니다.",
+  "references": [
+    "https://github.com/aspect-build/rules_esbuild",
+    "https://bun.sh/docs/api/http",
+    "https://hono.dev/concepts/context"
+  ],
+  "tags": ["slot", "api", "business-logic", "mandu"]
+}

package/src/resources/skills/mandu-slot/rules/_sections.md

@@ -0,0 +1,36 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Basic Structure (slot-basic)
+
+**Impact:** CRITICAL
+**Description:** Mandu.filling()을 default export로 사용하는 기본 구조. 이것 없이는 slot이 작동하지 않습니다.
+
+## 2. Context Response (slot-ctx)
+
+**Impact:** HIGH
+**Description:** ctx 객체의 응답 메서드 (ok, created, error 등) 사용법. 올바른 HTTP 상태 코드 반환에 필수적입니다.
+
+## 3. Guard & Auth (slot-guard)
+
+**Impact:** HIGH
+**Description:** guard()를 사용한 인증/인가 패턴. 보안이 필요한 API 엔드포인트에 필수입니다.
+
+## 4. HTTP Methods (slot-http)
+
+**Impact:** HIGH
+**Description:** get(), post(), put(), patch(), delete() 메서드 체이닝. RESTful API 설계의 핵심입니다.
+
+## 5. Lifecycle Hooks (slot-lifecycle)
+
+**Impact:** MEDIUM
+**Description:** onRequest, beforeHandle, afterHandle, afterResponse 훅. 로깅, 타이밍, 변환에 사용됩니다.
+
+## 6. Request Data (slot-request)
+
+**Impact:** MEDIUM
+**Description:** ctx.body(), ctx.params, ctx.query, ctx.headers 접근법. 요청 데이터 처리에 필요합니다.

package/src/resources/skills/mandu-slot/rules/_template.md

@@ -0,0 +1,63 @@
+# Rule Template
+
+Use this template when creating new rules for mandu-slot.
+
+---
+
+```markdown
+---
+title: Rule Title Here (명확하고 액션 가능한 제목)
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: 영향 설명 (예: "Required for slot to work", "2-5x improvement")
+tags: slot, tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: {LEVEL} ({impactDescription})**
+
+규칙의 목적과 중요성을 1-2문장으로 설명합니다.
+
+**Incorrect (문제점 설명):**
+
+\`\`\`typescript
+// 잘못된 예시 코드
+export default function handler(req) {
+  // 문제가 되는 패턴
+}
+\`\`\`
+
+**Correct (올바른 방법):**
+
+\`\`\`typescript
+// 올바른 예시 코드
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get((ctx) => {
+    return ctx.ok({ message: "Hello" });
+  });
+\`\`\`
+
+## Additional Context (선택사항)
+
+추가 설명이 필요한 경우 여기에 작성합니다.
+
+Reference: [관련 문서 링크](https://example.com)
+```
+
+---
+
+## Naming Convention
+
+- 파일명: `{section}-{rule-name}.md`
+- 예시: `slot-basic-structure.md`, `slot-ctx-response.md`
+
+## Impact Levels
+
+| Level | When to Use |
+|-------|-------------|
+| CRITICAL | 없으면 기능이 작동하지 않음 |
+| HIGH | 심각한 버그나 보안 문제 유발 |
+| MEDIUM | 성능이나 유지보수성에 영향 |
+| LOW | 모범 사례, 선택적 개선 |

package/src/resources/skills/mandu-slot/rules/slot-basic-structure.md

@@ -0,0 +1,38 @@
+---
+title: Always Use Mandu.filling() as Default Export
+impact: CRITICAL
+impactDescription: Required for slot to work
+tags: slot, structure, filling
+---
+
+## Always Use Mandu.filling() as Default Export
+
+Every slot file must export a default `Mandu.filling()` chain. This is how Mandu
+recognizes and processes your business logic.
+
+**Incorrect (plain function export):**
+
+```typescript
+// spec/slots/users.slot.ts
+export default async function handler(req: Request) {
+  return Response.json({ users: [] });
+}
+```
+
+**Correct (Mandu.filling() chain):**
+
+```typescript
+// spec/slots/users.slot.ts
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get((ctx) => {
+    return ctx.ok({ users: [] });
+  });
+```
+
+The `Mandu.filling()` provides:
+- Type-safe context API
+- Built-in error handling
+- Guard and lifecycle hooks
+- Consistent response format