start-vibing-stacks 2.6.0 → 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.**

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

@@ -1,3 +1,8 @@
+---
+name: scripting-automation
+version: 1.0.0
+---
+
 # Local Scripts & Automation — Python 3.12+
 
 **ALWAYS invoke when building local scripts, CLI tools, or automation tasks.**

package/stacks/python/stack.json

@@ -69,7 +69,8 @@
     "python-patterns",
     "pydantic-validation",
     "pytest-testing",
-    "python-performance"
+    "python-performance",
+    "api-security-python"
   ],
   "requirements": [
     {

package/stacks/python/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        python: ['3.12']
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Typecheck (mypy)
+        run: uv run mypy .
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Tests (pytest)
+        run: uv run pytest --tb=short --cov --cov-report=xml
+
+      - uses: codecov/codecov-action@v4
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+  security:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Audit dependencies
+        run: pip-audit --strict --vulnerability-service osv
+
+      - name: Gitleaks (secret scan)
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/stacks/python/workflows/security.yml

@@ -0,0 +1,56 @@
+name: Security
+
+on:
+  schedule:
+    - cron: '0 4 * * 1'
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install pip-audit
+      - run: pip-audit --strict
+
+  bandit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install bandit[toml]
+      - run: bandit -r . -ll -ii --exclude tests,test
+
+  gitleaks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  codeql:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@v3