openmoneta-dev-kit 1.9.0

package/skills/auth-bypass-testing/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: auth-bypass-testing
+description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu bypass auth cho test (vd 'thêm test bypass cho Playwright login', 'setup test user pattern'). KHÔNG tự trigger trong quy trình bình thường. Triển khai Test Bypass Flag an toàn để Playwright test có thể bypass OAuth/login mà không phá bảo mật production. 6 layer defense (env guard, IP whitelist 127.0.0.1, token rotation, double header, audit log, CI/CD guard)."
+---
+
+# Auth Bypass Testing — An toàn cho production
+
+Pattern để Playwright test **bypass OAuth/login** (Google, GitHub, ...) khi test mà KHÔNG mở lỗ hổng cho production.
+
+## Nguyên tắc 6 Layer Defense
+
+Tất cả layer phải pass cùng lúc thì bypass mới hoạt động:
+
+| Layer | Cơ chế | Vi phạm = chặn |
+|---|---|---|
+| 1. Env guard | `NODE_ENV !== 'production'` AND `ENABLE_TEST_BYPASS === 'true'` | Tree-shake trong build prod |
+| 2. IP whitelist | Chỉ accept `127.0.0.1`, `::1`, `localhost` | Reject mọi IP khác |
+| 3. Token rotation | Token random 64-char, sinh mỗi bootstrap, lưu `.env.test` (gitignored) | Token sai = 401 |
+| 4. Double header | Phải có `X-Test-Bypass-Token` AND `X-Test-User-Id` | Thiếu = 401 |
+| 5. Audit log | Log mọi request bypass vào `logs/test-bypass.log` | Để forensic |
+| 6. CI/CD guard | Pre-deploy script grep `ENABLE_TEST_BYPASS=true` trong prod config | Fail build |
+
+## Triển khai
+
+### Bước 1 — Tạo middleware bypass (theo stack)
+
+#### Express / Node.js
+
+```ts
+// src/middleware/test-bypass.ts
+import type { Request, Response, NextFunction } from 'express';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ALLOWED_IPS = (process.env.TEST_BYPASS_ALLOWED_IPS || '127.0.0.1,::1,localhost')
+  .split(',').map(s => s.trim());
+
+const LOG_PATH = path.resolve(process.cwd(), 'logs/test-bypass.log');
+
+export function testBypassMiddleware(req: Request, res: Response, next: NextFunction) {
+  // Layer 1: Env guard - sẽ bị tree-shake trong production build
+  if (process.env.NODE_ENV === 'production' || process.env.ENABLE_TEST_BYPASS !== 'true') {
+    return next();
+  }
+  
+  const token = req.header('X-Test-Bypass-Token');
+  const userId = req.header('X-Test-User-Id');
+  if (!token || !userId) return next();
+  
+  // Layer 2: IP whitelist
+  const ip = (req.ip || req.socket.remoteAddress || '').replace(/^::ffff:/, '');
+  if (!ALLOWED_IPS.includes(ip)) {
+    return res.status(403).json({ error: 'Test bypass: IP not allowed' });
+  }
+  
+  // Layer 3 + 4: Token check
+  const expectedToken = process.env.TEST_BYPASS_TOKEN;
+  if (!expectedToken || token !== expectedToken) {
+    return res.status(401).json({ error: 'Test bypass: invalid token' });
+  }
+  
+  // Validate userId thuộc fixture
+  const fixturePath = path.resolve(process.cwd(), 'tests/e2e/fixtures/test-users.json');
+  const fixtures = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+  const user = Object.values(fixtures).find((u: any) => u.id === userId);
+  if (!user) {
+    return res.status(401).json({ error: 'Test bypass: invalid user id' });
+  }
+  
+  // Layer 5: Audit log
+  fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+  fs.appendFileSync(LOG_PATH, JSON.stringify({
+    ts: new Date().toISOString(),
+    ip, userId, path: req.path, method: req.method,
+    ua: req.header('user-agent'),
+  }) + '\n');
+  
+  // Inject user vào request
+  (req as any).user = user;
+  next();
+}
+```
+
+Mount **trước** middleware auth thật:
+
+```ts
+app.use(testBypassMiddleware);
+app.use(realAuthMiddleware);
+```
+
+#### Next.js (App Router) — middleware.ts
+
+```ts
+// middleware.ts ở root
+import { NextRequest, NextResponse } from 'next/server';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ALLOWED_IPS = ['127.0.0.1', '::1', 'localhost'];
+
+export function middleware(req: NextRequest) {
+  if (process.env.NODE_ENV === 'production' || process.env.ENABLE_TEST_BYPASS !== 'true') {
+    return NextResponse.next();
+  }
+  
+  const token = req.headers.get('x-test-bypass-token');
+  const userId = req.headers.get('x-test-user-id');
+  if (!token || !userId) return NextResponse.next();
+  
+  const ip = req.ip || req.headers.get('x-forwarded-for') || '';
+  if (!ALLOWED_IPS.some(a => ip.includes(a))) {
+    return new NextResponse('IP not allowed', { status: 403 });
+  }
+  
+  if (token !== process.env.TEST_BYPASS_TOKEN) {
+    return new NextResponse('Invalid token', { status: 401 });
+  }
+  
+  // Set cookie/header để route handler đọc user
+  const res = NextResponse.next();
+  res.headers.set('x-bypass-user-id', userId);
+  return res;
+}
+```
+
+#### FastAPI (Python)
+
+```python
+# app/middleware/test_bypass.py
+from fastapi import Request, HTTPException
+from starlette.middleware.base import BaseHTTPMiddleware
+import os, json, datetime
+from pathlib import Path
+
+ALLOWED_IPS = os.getenv('TEST_BYPASS_ALLOWED_IPS', '127.0.0.1,::1,localhost').split(',')
+LOG_PATH = Path('logs/test-bypass.log')
+
+class TestBypassMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        if os.getenv('ENV') == 'production' or os.getenv('ENABLE_TEST_BYPASS') != 'true':
+            return await call_next(request)
+        
+        token = request.headers.get('x-test-bypass-token')
+        user_id = request.headers.get('x-test-user-id')
+        if not token or not user_id:
+            return await call_next(request)
+        
+        ip = (request.client.host if request.client else '').replace('::ffff:', '')
+        if ip not in ALLOWED_IPS:
+            raise HTTPException(403, 'Test bypass: IP not allowed')
+        
+        if token != os.getenv('TEST_BYPASS_TOKEN'):
+            raise HTTPException(401, 'Test bypass: invalid token')
+        
+        # Audit log
+        LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with LOG_PATH.open('a') as f:
+            f.write(json.dumps({
+                'ts': datetime.datetime.utcnow().isoformat(),
+                'ip': ip, 'user_id': user_id,
+                'path': request.url.path, 'method': request.method,
+            }) + '\n')
+        
+        request.state.bypass_user_id = user_id
+        return await call_next(request)
+```
+
+### Bước 2 — Test bypass với Playwright
+
+Header đã được inject tự động trong `playwright.config.ts` (xem `automated-testing`). Test có thể assume user đã login.
+
+### Bước 3 — Pre-deploy CI guard
+
+Tạo `scripts/check-no-bypass.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Fail build nếu phát hiện ENABLE_TEST_BYPASS=true trong production config
+PROD_FILES=(
+  ".env.production"
+  ".env.prod"
+  "ecosystem.config.js"
+  "Dockerfile"
+  "docker-compose.prod.yml"
+  "kubernetes/*.yaml"
+)
+
+FOUND=0
+for pattern in "${PROD_FILES[@]}"; do
+  for f in $pattern; do
+    [[ -f "$f" ]] || continue
+    if grep -E "ENABLE_TEST_BYPASS\s*[:=]\s*['\"]?true" "$f"; then
+      echo "[!] DANGER: ENABLE_TEST_BYPASS=true trong $f"
+      FOUND=1
+    fi
+  done
+done
+
+[[ $FOUND -eq 0 ]] && echo "✅ Pre-deploy check OK" || exit 1
+```
+
+Thêm vào CI pipeline (GitHub Actions):
+
+```yaml
+- name: Pre-deploy security check
+  run: bash scripts/check-no-bypass.sh
+```
+
+### Bước 4 — Verify trong Bước 5 (Security Check)
+
+Khi audit:
+- [ ] `ENABLE_TEST_BYPASS` chỉ enable trong `.env.test` (gitignored)
+- [ ] `.env.test` có trong `.gitignore`
+- [ ] Middleware có `process.env.NODE_ENV !== 'production'` guard
+- [ ] CI có `check-no-bypass.sh`
+- [ ] `logs/test-bypass.log` không chứa request từ IP lạ
+
+## Fallback: Storage State
+
+Khi cần test flow **không thể bypass** (vd: OAuth callback từ Google, đăng ký user mới):
+
+1. Login thủ công 1 lần với tài khoản test riêng (KHÔNG dùng tài khoản cá nhân).
+2. Playwright lưu cookies + localStorage vào `tests/.auth/user.json` (gitignored).
+3. Test sau dùng `storageState` để skip login.
+
+Xem skill `automated-testing` mục "Storage State".
+
+## Anti-patterns
+
+❌ Hardcode token trong code (phải qua env)
+❌ Bỏ IP check vì "test thôi mà"
+❌ Quên rotate token sau leak nghi ngờ
+❌ Log secret vào log file
+❌ Cho deploy với `ENABLE_TEST_BYPASS=true`

package/skills/automated-testing/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: automated-testing
+description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu E2E/UI test với Playwright (vd 'viết Playwright test cho checkout flow', 'chạy E2E mobile'). KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 6 Test khỏi core process). Cài và dùng Playwright multi-viewport (mobile/tablet/desktop), screenshot, fixture cho auth state. Có script install-playwright.sh để AI tự cài."
+---
+
+# Automated Testing với Playwright
+
+Bộ công cụ test tự động cho UI/UX. Dùng kết hợp với skill `ui-test-loop` (workflow loop fix) và `auth-bypass-testing` (qua auth).
+
+## Cài Playwright
+
+Chạy script tự động (idempotent):
+
+```bash
+bash ~/.cursor/skills/automated-testing/scripts/install-playwright.sh
+```
+
+Script sẽ:
+1. Detect package manager (`npm`/`pnpm`/`yarn`/`bun`).
+2. Cài `@playwright/test` + `dotenv`.
+3. Cài browser `chromium` (mặc định, tiết kiệm dung lượng).
+4. Tạo `playwright.config.ts` từ template nếu chưa có.
+5. Tạo `tests/e2e/auth.setup.ts` mẫu.
+
+## Cấu trúc tests/
+
+```
+tests/
+├── unit/                  # Vitest/Jest unit tests
+├── integration/           # Integration tests
+├── e2e/
+│   ├── auth.setup.ts      # Setup login state + test bypass header
+│   ├── *.spec.ts          # E2E specs
+│   └── fixtures/
+│       └── test-users.json
+├── screenshots/
+│   └── <plan-slug>/iter-<n>/  # Output ui-test-loop
+└── .auth/                 # GITIGNORED — Playwright storageState (nếu dùng)
+```
+
+## Pattern cơ bản
+
+### 1. Test multi-viewport
+
+`playwright.config.ts` đã setup 3 projects: mobile (375px), tablet (768px), desktop (1440px). Mặc định mọi spec chạy cả 3.
+
+```bash
+# Chạy tất cả 3 viewport
+npx playwright test
+
+# Chạy 1 viewport cụ thể
+npx playwright test --project=mobile
+
+# Chạy 1 spec
+npx playwright test login.spec.ts
+```
+
+### 2. Test với Test Bypass Auth
+
+Header `X-Test-Bypass-Token` đã được inject tự động vào mọi request qua `extraHTTPHeaders` trong config (xem template `playwright.config.ts.tpl`). Test có thể assume user đã login.
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test('user vào dashboard với test bypass', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.getByRole('heading', { name: /dashboard/i })).toBeVisible();
+});
+```
+
+### 3. Screenshot có cấu trúc
+
+```ts
+import { test } from '@playwright/test';
+
+test('Login button responsive', async ({ page }, testInfo) => {
+  await page.goto('/login');
+  
+  const planSlug = process.env.PLAN_SLUG || 'unknown';
+  const iter = process.env.UI_ITER || '0';
+  const dir = `tests/screenshots/${planSlug}/iter-${iter}`;
+  
+  await page.screenshot({
+    path: `${dir}/${testInfo.project.name}-login.png`,
+    fullPage: true,
+  });
+});
+```
+
+### 4. Visual regression (snapshot)
+
+```ts
+test('Login matches design', async ({ page }) => {
+  await page.goto('/login');
+  await expect(page).toHaveScreenshot('login.png', {
+    maxDiffPixels: 100,  // Cho phép sai tối đa 100 pixel
+  });
+});
+```
+
+Lần đầu chạy → tạo baseline. Lần sau → so sánh.
+
+### 5. Storage State (cho flow OAuth thật)
+
+Khi không thể bypass (vd: phải test OAuth callback từ Google thật), login 1 lần thủ công và lưu state:
+
+```ts
+// tests/e2e/auth.setup.ts
+import { test as setup } from '@playwright/test';
+
+setup('login Google', async ({ page }) => {
+  await page.goto('/login');
+  await page.click('button:has-text("Đăng nhập Google")');
+  // ... user thao tác manual lần đầu
+  await page.context().storageState({ path: 'tests/.auth/user.json' });
+});
+```
+
+```ts
+// playwright.config.ts — thêm
+export default defineConfig({
+  use: {
+    storageState: 'tests/.auth/user.json',
+  },
+});
+```
+
+## Chạy test trong CI
+
+```bash
+CI=1 npx playwright test --reporter=html
+```
+
+## Debug
+
+```bash
+# UI mode — xem step-by-step
+npx playwright test --ui
+
+# Headed — xem browser thật
+npx playwright test --headed
+
+# Trace viewer — xem trace của test fail
+npx playwright show-trace trace.zip
+```
+
+## Khi test fail
+
+1. Xem `tests/playwright-report/` (HTML report).
+2. Trace tự động lưu cho test fail (`retain-on-failure`).
+3. Apply skill `ui-test-loop` để loop fix.
+
+## Output bắt buộc cho hook `verify-completion`
+
+Sau khi chạy test, lưu kết quả:
+
+```bash
+# Ví dụ wrapper script
+RESULT=$(npx playwright test --reporter=json 2>&1)
+STATUS=$([[ $? == 0 ]] && echo "pass" || echo "fail")
+echo "{\"status\": \"$STATUS\", \"timestamp\": \"$(date -Iseconds)\", \"tool\": \"playwright\"}" > .cursor/.last-test-result
+```

package/skills/automated-testing/scripts/install-playwright.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# Cài Playwright cho project hiện tại. Idempotent - chạy lại không sao.
+# Usage: bash ~/.cursor/skills/automated-testing/scripts/install-playwright.sh [project-path]
+
+set -euo pipefail
+
+PROJECT_DIR="${1:-$(pwd)}"
+cd "$PROJECT_DIR"
+
+echo "==> Cài Playwright cho: $PROJECT_DIR"
+
+# Detect package manager
+if [[ -f bun.lockb || -f bun.lock ]]; then
+  PM=bun
+  ADD="bun add -d"
+elif [[ -f pnpm-lock.yaml ]]; then
+  PM=pnpm
+  ADD="pnpm add -D"
+elif [[ -f yarn.lock ]]; then
+  PM=yarn
+  ADD="yarn add -D"
+elif [[ -f package.json ]]; then
+  PM=npm
+  ADD="npm install -D"
+else
+  echo "[!] Không phát hiện package.json. Tạo dự án Node trước (npm init -y) rồi chạy lại."
+  exit 1
+fi
+
+echo "==> Package manager: $PM"
+
+# Check đã cài chưa
+if [[ -f node_modules/@playwright/test/package.json ]]; then
+  echo "==> @playwright/test đã cài, skip."
+else
+  echo "==> Cài @playwright/test và dotenv..."
+  $ADD @playwright/test dotenv
+fi
+
+# Cài browser chromium (mặc định, nhẹ nhất)
+echo "==> Cài Chromium browser cho Playwright..."
+npx playwright install chromium --with-deps 2>/dev/null || npx playwright install chromium
+
+# Copy playwright.config.ts từ template nếu chưa có
+TEMPLATE="$HOME/.cursor/templates/playwright.config.ts.tpl"
+TARGET="playwright.config.ts"
+if [[ -f "$TARGET" ]]; then
+  echo "==> $TARGET đã tồn tại, skip."
+elif [[ -f "$TEMPLATE" ]]; then
+  cp "$TEMPLATE" "$TARGET"
+  echo "==> Đã tạo $TARGET từ template."
+fi
+
+# Tạo tests/e2e/auth.setup.ts mẫu
+mkdir -p tests/e2e/fixtures
+AUTH_SETUP="tests/e2e/auth.setup.ts"
+if [[ ! -f "$AUTH_SETUP" ]]; then
+  cat > "$AUTH_SETUP" <<'EOF'
+import { test as setup, expect } from '@playwright/test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const AUTH_FILE = path.resolve(__dirname, '../.auth/user.json');
+
+/**
+ * Setup auth state. 2 cách:
+ * 1. Test Bypass Flag (recommended): header X-Test-Bypass-Token đã set
+ *    trong playwright.config.ts. Setup này chỉ sanity-check.
+ * 2. Storage State: login thật, lưu cookies/localStorage vào AUTH_FILE.
+ */
+setup('verify auth bypass works', async ({ request }) => {
+  const baseURL = process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:3000';
+  const token = process.env.TEST_BYPASS_TOKEN;
+  
+  if (!token) {
+    console.warn('[auth.setup] TEST_BYPASS_TOKEN không set. Bỏ qua bypass check.');
+    return;
+  }
+  
+  // Sanity: gọi endpoint health/me với header bypass
+  const res = await request.get(`${baseURL}/api/me`, {
+    headers: {
+      'X-Test-Bypass-Token': token,
+      'X-Test-User-Id': process.env.TEST_USER_ID_DEFAULT || '',
+    },
+    failOnStatusCode: false,
+  });
+  
+  if (res.status() === 404) {
+    console.warn('[auth.setup] Endpoint /api/me chưa có, skip sanity check.');
+    return;
+  }
+  
+  expect(res.status()).toBeLessThan(500);
+  console.log('[auth.setup] Bypass auth OK.');
+  
+  // Đảm bảo thư mục .auth tồn tại (không lưu state khi dùng bypass)
+  const dir = path.dirname(AUTH_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+});
+EOF
+  echo "==> Đã tạo $AUTH_SETUP mẫu."
+fi
+
+# Tạo tests/fixtures/test-users.json mẫu
+USERS_JSON="tests/e2e/fixtures/test-users.json"
+if [[ ! -f "$USERS_JSON" ]]; then
+  cat > "$USERS_JSON" <<'EOF'
+{
+  "default": {
+    "id": "00000000-0000-0000-0000-000000000001",
+    "email": "test-default@example.com",
+    "name": "Test User",
+    "role": "user"
+  },
+  "admin": {
+    "id": "00000000-0000-0000-0000-000000000002",
+    "email": "test-admin@example.com",
+    "name": "Test Admin",
+    "role": "admin"
+  }
+}
+EOF
+  echo "==> Đã tạo $USERS_JSON mẫu."
+fi
+
+echo ""
+echo "✅ Hoàn tất cài Playwright."
+echo ""
+echo "Chạy test: npx playwright test"
+echo "Chạy mobile only: npx playwright test --project=mobile"
+echo "UI mode: npx playwright test --ui"
+echo ""
+echo "Lưu ý: setup .env.test với TEST_BYPASS_TOKEN và backend của bạn phải có middleware bypass (xem skill auth-bypass-testing)."