start-vibing-stacks 2.5.1 → 2.7.0

package/stacks/python/skills/api-security-python/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: api-security-python
+version: 1.0.0
+description: Production-grade API hardening for Python (FastAPI, Django, Flask). Rate limit, CORS, JWT, secure cookies, CSRF, OAuth2.
+---
+
+# API Security — Python
+
+**ALWAYS invoke when building API endpoints, auth flows, or admin actions.**
+
+> Pair this with `security-baseline` for OWASP Top 10. This skill is stack-specific hardening.
+
+## Layered Defense
+
+```
+Edge (CDN/WAF) → Rate Limit → CORS → Headers → Auth → Authz → Validate → Logic → Encode → Audit
+```
+
+---
+
+## 1. Security Headers
+
+### FastAPI — middleware
+```python
+from fastapi import FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class SecurityHeaders(BaseHTTPMiddleware):
+    async def dispatch(self, request, call_next):
+        response = await call_next(request)
+        response.headers["Strict-Transport-Security"] = "max-age=63072000; includeSubDomains; preload"
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; "
+            "img-src 'self' data: https:; frame-ancestors 'none'"
+        )
+        return response
+
+app = FastAPI()
+app.add_middleware(SecurityHeaders)
+```
+
+### Django — `settings.py`
+```python
+SECURE_HSTS_SECONDS = 63072000
+SECURE_HSTS_INCLUDE_SUBDOMAINS = True
+SECURE_HSTS_PRELOAD = True
+SECURE_CONTENT_TYPE_NOSNIFF = True
+SECURE_REFERRER_POLICY = "strict-origin-when-cross-origin"
+SECURE_SSL_REDIRECT = True
+SESSION_COOKIE_SECURE = True
+SESSION_COOKIE_HTTPONLY = True
+SESSION_COOKIE_SAMESITE = "Lax"
+CSRF_COOKIE_SECURE = True
+CSRF_COOKIE_HTTPONLY = True
+X_FRAME_OPTIONS = "DENY"
+```
+
+---
+
+## 2. CORS — Strict Allowlist
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+import os
+
+ALLOW = [o.strip() for o in os.getenv("CORS_ORIGINS", "").split(",") if o]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOW,           # explicit list, NEVER ["*"] with credentials
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PATCH", "DELETE"],
+    allow_headers=["Authorization", "Content-Type", "X-CSRF-Token"],
+    max_age=600,
+)
+```
+
+**Never** `allow_origins=["*"]` with `allow_credentials=True` — browsers reject and auth silently breaks.
+
+---
+
+## 3. Rate Limiting
+
+### FastAPI — `slowapi`
+```python
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+
+limiter = Limiter(key_func=get_remote_address, storage_uri="redis://localhost:6379")
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+@app.post("/auth/login")
+@limiter.limit("5/15minutes")
+async def login(request: Request, body: LoginIn):
+    ...
+```
+
+### Django — `django-ratelimit`
+```python
+from django_ratelimit.decorators import ratelimit
+
+@ratelimit(key='ip', rate='5/15m', block=True)
+def login_view(request):
+    ...
+```
+
+**Limits to set:** auth (5/15min), password reset (3/hour), signup (3/hour/IP), generic write (60/min/user).
+
+---
+
+## 4. Cookies
+
+### FastAPI
+```python
+from fastapi import Response
+
+response.set_cookie(
+    key="session",
+    value=token,
+    httponly=True,                              # JS cannot read
+    secure=True,                                 # HTTPS only
+    samesite="lax",                              # 'strict' if no cross-site flows
+    max_age=60 * 60 * 24 * 7,                    # 7d
+    path="/",
+    domain=os.getenv("COOKIE_DOMAIN"),
+)
+```
+
+---
+
+## 5. JWT / OAuth2 — FastAPI
+
+```python
+from datetime import datetime, timedelta, timezone
+from jose import jwt, JWTError
+import os, uuid
+
+SECRET = os.environ["JWT_SECRET"]
+ALG = "HS256"
+
+def issue_access_token(user_id: str, role: str) -> str:
+    now = datetime.now(timezone.utc)
+    return jwt.encode(
+        {
+            "sub": user_id,
+            "role": role,
+            "iat": now,
+            "exp": now + timedelta(minutes=15),
+            "jti": str(uuid.uuid4()),
+        },
+        SECRET,
+        algorithm=ALG,
+    )
+
+async def current_user(token: str = Depends(oauth2_scheme)) -> User:
+    try:
+        payload = jwt.decode(token, SECRET, algorithms=[ALG])  # pin algorithm
+    except JWTError:
+        raise HTTPException(401, "Invalid token")
+    user = await User.get_or_none(id=payload["sub"])
+    if not user:
+        raise HTTPException(401, "User not found")
+    return user
+```
+
+Rules:
+- Access tokens: ≤ 15 min. Refresh tokens: rotate on use, store hash in DB, revocable.
+- Pin `algorithms=[ALG]`. Never accept `alg: none`.
+- Include `jti` for revocation lists.
+
+---
+
+## 6. CSRF
+
+### Django
+Built-in: `django.middleware.csrf.CsrfViewMiddleware`. Always enabled — never disable globally.
+For DRF + SessionAuth, use `@ensure_csrf_cookie` on the view that bootstraps the SPA.
+
+### FastAPI — double-submit cookie
+```python
+import secrets
+from fastapi import Request, HTTPException
+
+CSRF_COOKIE = "csrf-token"
+CSRF_HEADER = "x-csrf-token"
+UNSAFE = {"POST", "PUT", "PATCH", "DELETE"}
+
+@app.middleware("http")
+async def csrf(request: Request, call_next):
+    if request.method in UNSAFE:
+        cookie = request.cookies.get(CSRF_COOKIE)
+        header = request.headers.get(CSRF_HEADER)
+        if not cookie or cookie != header:
+            raise HTTPException(403, "CSRF")
+    response = await call_next(request)
+    if not request.cookies.get(CSRF_COOKIE):
+        response.set_cookie(CSRF_COOKIE, secrets.token_urlsafe(32),
+                            secure=True, samesite="lax", path="/")
+    return response
+```
+
+---
+
+## 7. Input Validation Boundary (Pydantic)
+
+```python
+from pydantic import BaseModel, EmailStr, Field, ConfigDict
+
+class CreateUser(BaseModel):
+    model_config = ConfigDict(extra="forbid")    # rejects unknown keys → blocks mass assignment
+    email: EmailStr = Field(max_length=254)
+    age: int = Field(ge=13, le=120)
+
+@app.post("/users")
+async def create(body: CreateUser):  # FastAPI validates automatically; 422 on failure
+    ...
+```
+
+---
+
+## 8. File Upload
+
+```python
+import magic                          # python-magic — reads magic bytes
+ALLOWED = {"image/jpeg", "image/png", "image/webp"}
+
+async def upload(file: UploadFile = File(...)):
+    if file.size and file.size > 10 * 1024 * 1024:
+        raise HTTPException(413, "Too large")
+    head = await file.read(2048)
+    mime = magic.from_buffer(head, mime=True)
+    if mime not in ALLOWED:
+        raise HTTPException(415, "Unsupported type")
+    await file.seek(0)
+    # Save with UUID name, outside webroot
+```
+
+---
+
+## 9. Password Hashing
+
+```python
+from argon2 import PasswordHasher
+ph = PasswordHasher(memory_cost=19_456, time_cost=2, parallelism=1)
+
+hashed = ph.hash(password)
+try:
+    ph.verify(hashed, attempt)
+except argon2.exceptions.VerifyMismatchError:
+    raise HTTPException(401, "Invalid credentials")
+
+if ph.check_needs_rehash(hashed):    # transparent upgrade
+    user.password = ph.hash(attempt)
+```
+
+Argon2id is the modern default. Avoid bare `hashlib`. For Django, the framework handles this — don't reinvent it.
+
+---
+
+## 10. SQL Injection — Use ORM Bindings
+
+```python
+# WRONG — string interpolation
+cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
+
+# CORRECT — parameterized
+cursor.execute("SELECT * FROM users WHERE id = %s", [user_id])
+
+# CORRECT — ORM
+user = await User.get(id=user_id)                   # Tortoise / SQLAlchemy / Django ORM
+```
+
+`SQLAlchemy.text()` with `:param` bindings is also safe. Raw f-strings are not.
+
+---
+
+## Endpoint Checklist
+
+- [ ] `Depends(current_user)` for protected routes
+- [ ] User ID from `current_user`, **never** from body
+- [ ] Pydantic model with `extra="forbid"`
+- [ ] Authz check on the resource (object-level)
+- [ ] Rate limit applied to auth + writes
+- [ ] No PII in logs
+- [ ] Errors: `HTTPException` with generic detail; full info to logs only
+
+## FORBIDDEN Patterns
+
+| Anti-pattern | Reason |
+|---|---|
+| `allow_origins=["*"]` with credentials | Browsers reject; auth breaks |
+| Calling `jwt.decode` without `algorithms=` | `alg: none` and confusion attacks |
+| Storing JWT in `localStorage` | XSS exfiltration |
+| Disabling Django `CsrfViewMiddleware` globally | CSRF wide open |
+| f-string interpolation in SQL | SQL injection |
+| Deserializing untrusted bytes (pickle, marshal, shelve) | RCE via gadget chains — use JSON |
+| `eval` / `exec` on user input | RCE |
+| Logging request body or headers raw | Leaks passwords, cookies, tokens |
+| Shell-mode subprocess with user input | Command injection — use list args, no shell |
+
+## See Also
+
+- `security-baseline` — OWASP Top 10
+- `secrets-management` — env vars, rotation
+- `pydantic-validation` — schema patterns
+- `observability` — structured logs without PII

package/stacks/python/skills/async-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: async-patterns
+version: 1.0.0
+---
+
 # Async Python Patterns — Concurrency & Performance
 
 **ALWAYS invoke when writing async/await code or concurrent operations.**

package/stacks/python/skills/django-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: django-patterns
+version: 1.0.0
+---
+
 # Django Patterns — Full-Stack Python (Django 5+)
 
 **ALWAYS invoke when writing Django models, views, or serializers.**

package/stacks/python/skills/fastapi-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: fastapi-patterns
+version: 1.0.0
+---
+
 # FastAPI Patterns — High-Performance Async APIs
 
 **ALWAYS invoke when writing FastAPI routes, dependencies, or middleware.**

package/stacks/python/skills/pydantic-validation/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: pydantic-validation
+version: 1.0.0
+---
+
 # Pydantic Validation — Runtime Type Safety for Python
 
 **ALWAYS use Pydantic for API schemas, config, and data boundaries.**

package/stacks/python/skills/pytest-testing/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: pytest-testing
+version: 1.0.0
+---
+
 # Pytest Testing — Python Testing Patterns
 
 **ALWAYS invoke AFTER implementing any feature.**

package/stacks/python/skills/python-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: python-patterns
+version: 1.0.0
+---
+
 # Python Patterns — Architecture & Decision-Making
 
 **ALWAYS invoke when making Python architecture decisions.**
@@ -6,11 +11,13 @@
 
 ```
 What are you building?
-├── API / Microservices     → FastAPI (async, Pydantic, fast)
-├── Full-stack / CMS / Admin → Django (batteries-included)
-├── Simple / Script         → Flask (minimal)
-├── AI/ML API serving       → FastAPI (Pydantic, uvicorn)
-└── Background workers      → Celery + any framework
+├── API / Microservices       → FastAPI (async, Pydantic, fast)
+├── Full-stack / CMS / Admin  → Django (batteries-included)
+├── Lightweight web app       → Flask (minimal)
+├── AI/ML API serving         → FastAPI (Pydantic, uvicorn)
+├── Local scripts / automation → Scripts (httpx, argparse, rich)
+├── WordPress / Ads / ETL     → Scripts (no framework needed)
+└── Background workers        → Celery + any framework
 ```
 
 ## Async vs Sync
@@ -74,6 +81,20 @@ myproject/
 └── tests/
 ```
 
+### Local Scripts / Automation
+```
+project/
+├── main.py           # CLI entry (argparse + match/case)
+├── scripts/          # One module per task
+├── lib/
+│   ├── config.py     # Pydantic Settings (.env)
+│   ├── http_client.py # httpx + tenacity retry
+│   └── logger.py     # rich logging
+├── data/             # Input/output files
+├── logs/
+└── tests/
+```
+
 ## Error Handling
 
 ```python

package/stacks/python/skills/python-performance/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: python-performance
+version: 1.0.0
+---
+
 # Python Performance — Profiling & Optimization
 
 **ALWAYS invoke when optimizing slow Python code.**

package/stacks/python/skills/scripting-automation/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: scripting-automation
+version: 1.0.0
+---
+
+# Local Scripts & Automation — Python 3.12+
+
+**ALWAYS invoke when building local scripts, CLI tools, or automation tasks.**
+
+## When to Use
+
+- WordPress API automation (create/update posts, manage media)
+- Ad campaign management (Google Ads, Facebook Ads, TikTok Ads API)
+- Data pipelines (CSV/Excel processing, database sync)
+- Web scraping and data extraction
+- File system operations and batch processing
+- Scheduled tasks and cron-like automation
+- API integrations without a web framework
+
+## Project Structure
+
+```
+project/
+├── pyproject.toml        # Dependencies + project metadata
+├── .env                  # API keys, credentials (NEVER commit)
+├── .env.example          # Template without real values
+├── scripts/
+│   ├── __init__.py
+│   ├── wordpress.py      # WordPress automation
+│   ├── ads_manager.py    # Ad campaigns
+│   └── data_sync.py      # Database sync
+├── lib/
+│   ├── __init__.py
+│   ├── http_client.py    # Reusable httpx client
+│   ├── config.py         # Pydantic Settings
+│   ├── logger.py         # Structured logging
+│   └── retry.py          # Retry with backoff
+├── data/                 # Input/output data files
+├── logs/                 # Log files
+├── tests/
+│   └── test_scripts.py
+└── main.py               # Entry point / CLI
+```
+
+## Configuration (Pydantic Settings)
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    WP_URL: str
+    WP_USER: str
+    WP_APP_PASSWORD: str
+
+    GOOGLE_ADS_DEVELOPER_TOKEN: str = ""
+    FACEBOOK_ACCESS_TOKEN: str = ""
+    TIKTOK_ACCESS_TOKEN: str = ""
+
+    DB_HOST: str = "localhost"
+    DB_PORT: int = 3306
+    DB_NAME: str
+    DB_USER: str
+    DB_PASSWORD: str
+
+    LOG_LEVEL: str = "INFO"
+    DRY_RUN: bool = False
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+settings = Settings()
+```
+
+## HTTP Client (reusable)
+
+```python
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+class ApiClient:
+    def __init__(self, base_url: str, auth: tuple[str, str] | None = None):
+        self.client = httpx.Client(
+            base_url=base_url,
+            auth=auth,
+            timeout=30.0,
+            headers={"User-Agent": "AutomationScript/1.0"},
+        )
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def get(self, path: str, **kwargs) -> dict:
+        r = self.client.get(path, **kwargs)
+        r.raise_for_status()
+        return r.json()
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def post(self, path: str, **kwargs) -> dict:
+        r = self.client.post(path, **kwargs)
+        r.raise_for_status()
+        return r.json()
+
+    def close(self):
+        self.client.close()
+```
+
+## WordPress REST API Pattern
+
+```python
+from lib.http_client import ApiClient
+from lib.config import settings
+
+wp = ApiClient(
+    base_url=f"{settings.WP_URL}/wp-json/wp/v2",
+    auth=(settings.WP_USER, settings.WP_APP_PASSWORD),
+)
+
+def create_post(title: str, content: str, status: str = "draft") -> dict:
+    return wp.post("/posts", json={
+        "title": title,
+        "content": content,
+        "status": status,
+    })
+
+def update_post(post_id: int, **fields) -> dict:
+    return wp.post(f"/posts/{post_id}", json=fields)
+
+def bulk_update_posts(posts: list[dict]) -> list[dict]:
+    results = []
+    for post in posts:
+        pid = post.pop("id")
+        result = update_post(pid, **post)
+        results.append(result)
+        logger.info(f"Updated post {pid}: {result['title']['rendered']}")
+    return results
+```
+
+## Database Access (direct, no ORM)
+
+```python
+import mariadb
+from contextlib import contextmanager
+from lib.config import settings
+
+@contextmanager
+def get_connection():
+    conn = mariadb.connect(
+        host=settings.DB_HOST,
+        port=settings.DB_PORT,
+        user=settings.DB_USER,
+        password=settings.DB_PASSWORD,
+        database=settings.DB_NAME,
+    )
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+def fetch_all(query: str, params: tuple = ()) -> list[dict]:
+    with get_connection() as conn:
+        cursor = conn.cursor(dictionary=True)
+        cursor.execute(query, params)
+        return cursor.fetchall()
+
+def execute(query: str, params: tuple = ()) -> int:
+    with get_connection() as conn:
+        cursor = conn.cursor()
+        cursor.execute(query, params)
+        conn.commit()
+        return cursor.rowcount
+```
+
+## CLI Entry Point
+
+```python
+import argparse
+import logging
+from lib.config import settings
+
+logging.basicConfig(
+    level=getattr(logging, settings.LOG_LEVEL),
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    handlers=[
+        logging.StreamHandler(),
+        logging.FileHandler("logs/script.log"),
+    ],
+)
+logger = logging.getLogger(__name__)
+
+def main():
+    parser = argparse.ArgumentParser(description="Automation Scripts")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("wp-sync", help="Sync WordPress posts")
+    sub.add_parser("ads-report", help="Generate ads performance report")
+    sub.add_parser("db-migrate", help="Run data migration")
+
+    args = parser.parse_args()
+
+    if settings.DRY_RUN:
+        logger.warning("DRY RUN mode — no changes will be saved")
+
+    match args.command:
+        case "wp-sync":
+            from scripts.wordpress import sync_posts
+            sync_posts()
+        case "ads-report":
+            from scripts.ads_manager import generate_report
+            generate_report()
+        case "db-migrate":
+            from scripts.data_sync import run_migration
+            run_migration()
+        case _:
+            parser.print_help()
+
+if __name__ == "__main__":
+    main()
+```
+
+## Essential Libraries
+
+```toml
+# pyproject.toml
+[project]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic-settings>=2.0",
+    "tenacity>=8.0",
+    "python-dotenv>=1.0",
+    "mariadb>=1.1",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "mypy>=1.8", "ruff>=0.3"]
+ads = ["google-ads>=24.0", "facebook-business>=19.0"]
+```
+
+## Logging (structured)
+
+```python
+from rich.console import Console
+from rich.logging import RichHandler
+import logging
+
+console = Console()
+logging.basicConfig(
+    level="INFO",
+    format="%(message)s",
+    handlers=[RichHandler(console=console, rich_tracebacks=True)],
+)
+```
+
+## FORBIDDEN
+
+1. **Hardcoded credentials** — use `.env` + Pydantic Settings
+2. **No error handling on API calls** — always try/except + retry
+3. **No logging** — every script must log actions and errors
+4. **`requests` library** — use `httpx` (modern, sync+async)
+5. **Print statements for output** — use `logging` or `rich`
+6. **No `--dry-run` flag** — destructive scripts must support dry run
+7. **SQL without parameterization** — always use `?` placeholders
+8. **No `.env.example`** — always provide template for credentials