@mandujs/mcp 0.9.19 → 0.9.21

package/src/resources/skills/mandu-performance/rules/perf-render-transitions.md

@@ -0,0 +1,154 @@
+---
+title: Use startTransition for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: Prevents UI blocking on heavy updates
+tags: performance, render, transitions, react
+---
+
+## Use startTransition for Non-Urgent Updates
+
+**Impact: MEDIUM (Prevents UI blocking on heavy updates)**
+
+`startTransition`으로 비긴급 업데이트를 표시하면 React가 긴급 업데이트(타이핑, 클릭)를 우선 처리합니다.
+
+**Incorrect (모든 업데이트가 긴급):**
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+export default function SearchIsland() {
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState([]);
+
+  const handleChange = async (e) => {
+    const value = e.target.value;
+    setQuery(value);  // 긴급: 입력 반영
+
+    // ❌ 검색도 긴급으로 처리 → 입력이 버벅임
+    const data = await search(value);
+    setResults(data);
+  };
+
+  return (
+    <div>
+      <input value={query} onChange={handleChange} />
+      <ResultsList results={results} />
+    </div>
+  );
+}
+```
+
+**Correct (비긴급 업데이트 분리):**
+
+```tsx
+"use client";
+
+import { useState, useTransition } from "react";
+
+export default function SearchIsland() {
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState([]);
+  const [isPending, startTransition] = useTransition();
+
+  const handleChange = async (e) => {
+    const value = e.target.value;
+    setQuery(value);  // 긴급: 입력 즉시 반영
+
+    // ✅ 검색 결과는 비긴급
+    startTransition(async () => {
+      const data = await search(value);
+      setResults(data);
+    });
+  };
+
+  return (
+    <div>
+      <input value={query} onChange={handleChange} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </div>
+  );
+}
+```
+
+## 무거운 리스트 필터링
+
+```tsx
+"use client";
+
+import { useState, useTransition, useMemo } from "react";
+
+export default function FilterableList({ items }) {
+  const [filter, setFilter] = useState("");
+  const [isPending, startTransition] = useTransition();
+
+  // ✅ 필터링을 transition으로 처리
+  const handleFilterChange = (e) => {
+    startTransition(() => {
+      setFilter(e.target.value);
+    });
+  };
+
+  const filteredItems = useMemo(
+    () => items.filter((item) => item.name.includes(filter)),
+    [items, filter]
+  );
+
+  return (
+    <div>
+      <input
+        onChange={handleFilterChange}
+        placeholder="Filter..."
+      />
+      <div style={{ opacity: isPending ? 0.7 : 1 }}>
+        {filteredItems.map((item) => (
+          <Item key={item.id} data={item} />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## 탭 전환
+
+```tsx
+"use client";
+
+import { useState, useTransition } from "react";
+
+export default function TabsIsland() {
+  const [tab, setTab] = useState("home");
+  const [isPending, startTransition] = useTransition();
+
+  const handleTabChange = (newTab) => {
+    // ✅ 탭 콘텐츠 로딩은 비긴급
+    startTransition(() => {
+      setTab(newTab);
+    });
+  };
+
+  return (
+    <div>
+      <TabButtons activeTab={tab} onChange={handleTabChange} />
+      <div style={{ opacity: isPending ? 0.5 : 1 }}>
+        <TabContent tab={tab} />
+      </div>
+    </div>
+  );
+}
+```
+
+## 언제 사용하나요?
+
+| 상황 | startTransition 사용 |
+|------|---------------------|
+| 타이핑, 클릭 반응 | ❌ (긴급) |
+| 검색 결과 표시 | ✅ |
+| 리스트 필터링 | ✅ |
+| 탭/페이지 전환 | ✅ |
+| 무거운 계산 결과 | ✅ |
+
+Reference: [React useTransition](https://react.dev/reference/react/useTransition)

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

@@ -0,0 +1,87 @@
+---
+name: mandu-security
+description: |
+  Security best practices for Mandu applications. Use when implementing
+  authentication, authorization, input validation, or protecting against
+  common vulnerabilities. Triggers on guard, auth, CSRF, XSS, or security tasks.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu Security
+
+Mandu 애플리케이션의 보안 모범 사례 가이드. slot guard를 통한 인증/인가, 입력 검증, CSRF/XSS 방어, 환경 변수 관리를 다룹니다.
+
+## When to Apply
+
+Reference these guidelines when:
+- Implementing authentication in slots
+- Adding authorization guards
+- Validating user input
+- Protecting against CSRF/XSS attacks
+- Managing secrets and environment variables
+- Handling sensitive data
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Authentication | CRITICAL | `sec-auth-` |
+| 2 | Input Validation | CRITICAL | `sec-input-` |
+| 3 | CSRF/XSS Protection | HIGH | `sec-protect-` |
+| 4 | Environment & Secrets | HIGH | `sec-env-` |
+| 5 | Data Handling | MEDIUM | `sec-data-` |
+
+## Quick Reference
+
+### 1. Authentication (CRITICAL)
+
+- `sec-auth-guard` - Use guard() for authentication checks
+- `sec-auth-session` - Secure session management
+- `sec-auth-jwt` - JWT token handling best practices
+
+### 2. Input Validation (CRITICAL)
+
+- `sec-input-validate` - Always validate and sanitize input
+- `sec-input-schema` - Use schema validation (Zod, etc.)
+- `sec-input-escape` - Escape output to prevent injection
+
+### 3. CSRF/XSS Protection (HIGH)
+
+- `sec-protect-csrf` - CSRF token implementation
+- `sec-protect-xss` - XSS prevention techniques
+- `sec-protect-headers` - Security headers configuration
+
+### 4. Environment & Secrets (HIGH)
+
+- `sec-env-management` - Environment variable best practices
+- `sec-env-no-expose` - Never expose secrets to client
+
+### 5. Data Handling (MEDIUM)
+
+- `sec-data-sanitize` - Sanitize data before storage
+- `sec-data-encrypt` - Encrypt sensitive data
+
+## Security Checklist
+
+```
+□ Authentication required for protected routes
+□ Input validated on server side
+□ Output escaped/sanitized
+□ CSRF tokens for state-changing operations
+□ Security headers configured
+□ Secrets in environment variables only
+□ No sensitive data in client bundles
+```
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/sec-auth-guard.md
+rules/sec-input-validate.md
+rules/sec-protect-csrf.md
+```

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

@@ -0,0 +1,13 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "February 2026",
+  "abstract": "Mandu 애플리케이션 보안 모범 사례 가이드. slot guard 인증/인가, 입력 검증 및 스키마 유효성 검사, CSRF/XSS 방어, 보안 헤더, 환경 변수 및 시크릿 관리를 다룹니다.",
+  "references": [
+    "https://owasp.org/www-project-top-ten/",
+    "https://cheatsheetseries.owasp.org/",
+    "https://bun.sh/docs/api/hashing",
+    "https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP"
+  ],
+  "tags": ["security", "auth", "csrf", "xss", "validation", "mandu"]
+}

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

@@ -0,0 +1,31 @@
+# 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. Authentication (sec-auth)
+
+**Impact:** CRITICAL
+**Description:** slot guard를 통한 인증 구현. 보호된 리소스에 대한 접근 제어의 첫 번째 방어선입니다.
+
+## 2. Input Validation (sec-input)
+
+**Impact:** CRITICAL
+**Description:** 모든 사용자 입력의 검증과 살균. SQL Injection, Command Injection 등의 주입 공격 방어에 필수입니다.
+
+## 3. CSRF/XSS Protection (sec-protect)
+
+**Impact:** HIGH
+**Description:** Cross-Site Request Forgery와 Cross-Site Scripting 방어. 웹 애플리케이션의 대표적인 취약점입니다.
+
+## 4. Environment & Secrets (sec-env)
+
+**Impact:** HIGH
+**Description:** 환경 변수와 시크릿 관리. API 키, 데이터베이스 비밀번호 등 민감 정보 보호에 필수입니다.
+
+## 5. Data Handling (sec-data)
+
+**Impact:** MEDIUM
+**Description:** 민감 데이터의 안전한 처리. 암호화, 해싱, 마스킹 등의 기법을 다룹니다.

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

@@ -0,0 +1,74 @@
+# Rule Template
+
+Use this template when creating new rules for mandu-security.
+
+---
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: 영향 설명 (예: "Prevents unauthorized access")
+tags: security, tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: {LEVEL} ({impactDescription})**
+
+보안 규칙의 목적과 중요성을 설명합니다.
+
+**Vulnerable (취약한 코드):**
+
+\`\`\`typescript
+// ❌ 보안 취약점이 있는 코드
+export default Mandu.filling()
+  .get(async (ctx) => {
+    // 인증 없이 민감 데이터 반환
+    const users = await db.user.findMany();
+    return ctx.ok({ users });
+  });
+\`\`\`
+
+**Secure (안전한 코드):**
+
+\`\`\`typescript
+// ✅ 보안이 강화된 코드
+export default Mandu.filling()
+  .guard((ctx) => {
+    if (!ctx.get("user")?.isAdmin) {
+      return ctx.forbidden("Admin access required");
+    }
+  })
+  .get(async (ctx) => {
+    const users = await db.user.findMany();
+    return ctx.ok({ users });
+  });
+\`\`\`
+
+## Attack Vector
+
+이 취약점이 어떻게 악용될 수 있는지 설명합니다.
+
+## Mitigation
+
+추가적인 방어 방법을 설명합니다.
+
+Reference: [OWASP 관련 문서](https://owasp.org/)
+```
+
+---
+
+## Naming Convention
+
+- 파일명: `sec-{category}-{rule-name}.md`
+- 예시: `sec-auth-guard.md`, `sec-input-validate.md`
+
+## OWASP Top 10 Reference
+
+| # | Category | Related Rules |
+|---|----------|---------------|
+| 1 | Broken Access Control | sec-auth-* |
+| 2 | Cryptographic Failures | sec-data-* |
+| 3 | Injection | sec-input-* |
+| 7 | XSS | sec-protect-xss |

package/src/resources/skills/mandu-security/rules/sec-auth-guard.md

@@ -0,0 +1,127 @@
+---
+title: Use guard() for Authentication Checks
+impact: CRITICAL
+impactDescription: Prevents unauthorized access
+tags: security, auth, guard, slot
+---
+
+## Use guard() for Authentication Checks
+
+**Impact: CRITICAL (Prevents unauthorized access)**
+
+모든 보호된 slot에서 `guard()`를 사용하여 인증을 확인하세요. guard는 핸들러 실행 전에 검사됩니다.
+
+**Vulnerable (인증 없음):**
+
+```typescript
+// ❌ 인증 체크 없이 민감 데이터 노출
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const users = await db.user.findMany();
+    return ctx.ok({ users });  // 누구나 접근 가능!
+  });
+```
+
+**Secure (guard로 인증):**
+
+```typescript
+// ✅ guard로 인증 체크
+export default Mandu.filling()
+  .guard((ctx) => {
+    const user = ctx.get("user");
+    if (!user) {
+      return ctx.unauthorized("Authentication required");
+    }
+    // void 반환 시 계속 진행
+  })
+  .get(async (ctx) => {
+    const users = await db.user.findMany();
+    return ctx.ok({ users });
+  });
+```
+
+## 역할 기반 접근 제어 (RBAC)
+
+```typescript
+export default Mandu.filling()
+  .guard((ctx) => {
+    const user = ctx.get("user");
+
+    if (!user) {
+      return ctx.unauthorized("Login required");
+    }
+
+    if (!user.roles.includes("admin")) {
+      return ctx.forbidden("Admin access required");
+    }
+  })
+  .get(async (ctx) => {
+    // 관리자만 접근 가능
+    const sensitiveData = await db.audit.findMany();
+    return ctx.ok({ data: sensitiveData });
+  });
+```
+
+## 리소스 소유권 검증
+
+```typescript
+export default Mandu.filling()
+  .guard(async (ctx) => {
+    const user = ctx.get("user");
+    const resourceId = ctx.params.id;
+
+    if (!user) {
+      return ctx.unauthorized("Login required");
+    }
+
+    // 리소스 소유권 확인
+    const resource = await db.resource.findUnique({
+      where: { id: resourceId },
+    });
+
+    if (resource?.ownerId !== user.id) {
+      return ctx.forbidden("You don't own this resource");
+    }
+
+    // 나중에 사용할 수 있도록 저장
+    ctx.set("resource", resource);
+  })
+  .get((ctx) => {
+    const resource = ctx.get("resource");
+    return ctx.ok({ resource });
+  })
+  .delete(async (ctx) => {
+    const resource = ctx.get("resource");
+    await db.resource.delete({ where: { id: resource.id } });
+    return ctx.noContent();
+  });
+```
+
+## 다중 guard 체이닝
+
+```typescript
+const requireAuth = (ctx) => {
+  if (!ctx.get("user")) {
+    return ctx.unauthorized("Login required");
+  }
+};
+
+const requireAdmin = (ctx) => {
+  if (!ctx.get("user")?.isAdmin) {
+    return ctx.forbidden("Admin required");
+  }
+};
+
+export default Mandu.filling()
+  .guard(requireAuth)
+  .guard(requireAdmin)  // 순차적으로 실행
+  .get(/* ... */);
+```
+
+## 주의사항
+
+- guard에서 응답을 반환하면 핸들러가 실행되지 않음
+- void 반환 시 다음 guard 또는 핸들러로 진행
+- 인증 미들웨어에서 `ctx.set("user", user)`로 사용자 정보 저장
+
+Reference: [OWASP Broken Access Control](https://owasp.org/Top10/A01_2021-Broken_Access_Control/)

package/src/resources/skills/mandu-security/rules/sec-env-management.md

@@ -0,0 +1,133 @@
+---
+title: Secure Environment Variable Management
+impact: HIGH
+impactDescription: Prevents secret exposure
+tags: security, env, secrets, configuration
+---
+
+## Secure Environment Variable Management
+
+**Impact: HIGH (Prevents secret exposure)**
+
+시크릿과 민감한 설정은 환경 변수로 관리하고, 절대 코드에 하드코딩하지 마세요.
+
+**Vulnerable (하드코딩된 시크릿):**
+
+```typescript
+// ❌ 코드에 시크릿 하드코딩
+const db = new Database({
+  host: "prod-db.example.com",
+  password: "super_secret_password",  // 위험!
+});
+
+const stripe = new Stripe("sk_live_abc123xyz");  // 위험!
+```
+
+**Secure (환경 변수 사용):**
+
+```typescript
+// ✅ 환경 변수에서 로드
+const db = new Database({
+  host: process.env.DATABASE_HOST,
+  password: process.env.DATABASE_PASSWORD,
+});
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+```
+
+## 환경 변수 검증
+
+```typescript
+// lib/env.ts
+import { z } from "zod";
+
+const envSchema = z.object({
+  // 필수
+  DATABASE_URL: z.string().url(),
+  SESSION_SECRET: z.string().min(32),
+  STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+
+  // 선택 (기본값)
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+  PORT: z.coerce.number().default(3000),
+
+  // 프로덕션에서만 필수
+  SENTRY_DSN: z.string().url().optional(),
+});
+
+// 앱 시작 시 검증
+export const env = envSchema.parse(process.env);
+
+// 타입 안전한 접근
+console.log(env.DATABASE_URL);  // string
+console.log(env.PORT);          // number
+```
+
+## .env 파일 관리
+
+```bash
+# .env.example (커밋됨 - 템플릿)
+DATABASE_URL=postgresql://user:password@localhost:5432/db
+SESSION_SECRET=change_me_to_random_32_char_string
+STRIPE_SECRET_KEY=sk_test_xxx
+
+# .env.local (커밋 안 됨 - 실제 값)
+DATABASE_URL=postgresql://admin:real_password@prod-db:5432/myapp
+SESSION_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+STRIPE_SECRET_KEY=sk_live_real_key_here
+```
+
+## .gitignore 설정
+
+```gitignore
+# 환경 변수 파일
+.env
+.env.local
+.env.*.local
+
+# 시크릿 관련
+*.pem
+*.key
+credentials.json
+```
+
+## 클라이언트에 노출되지 않도록 주의
+
+```typescript
+// ❌ 클라이언트 번들에 포함됨
+// app/page.tsx
+const apiKey = process.env.API_SECRET_KEY;  // 위험!
+
+// ✅ 서버에서만 사용
+// spec/slots/api.slot.ts
+export default Mandu.filling()
+  .get(async (ctx) => {
+    // 서버 측에서만 접근
+    const apiKey = process.env.API_SECRET_KEY;
+    const data = await fetchExternalApi(apiKey);
+    return ctx.ok({ data });  // apiKey는 반환하지 않음
+  });
+```
+
+## 시크릿 로테이션
+
+```typescript
+// 여러 버전의 시크릿 지원
+const CURRENT_SECRET = process.env.SESSION_SECRET!;
+const PREVIOUS_SECRET = process.env.SESSION_SECRET_PREVIOUS;
+
+function verifyToken(token: string): boolean {
+  // 현재 시크릿으로 먼저 검증
+  if (verify(token, CURRENT_SECRET)) return true;
+
+  // 이전 시크릿으로도 검증 (로테이션 기간)
+  if (PREVIOUS_SECRET && verify(token, PREVIOUS_SECRET)) {
+    // 토큰 갱신 권장
+    return true;
+  }
+
+  return false;
+}
+```
+
+Reference: [12-Factor App Config](https://12factor.net/config)