start-vibing-stacks 2.17.0 → 2.19.0

package/stacks/frontend/react/skills/zod-validation/SKILL.md

@@ -1,42 +1,97 @@
 ---
 name: zod-validation
-version: 1.0.0
+version: 2.0.0
+description: "Zod 4 (stable Aug 2025) runtime validation for TypeScript boundaries — forms, API responses, env vars, server actions. Zod 4 brings 14× faster string parsing, 7× array, 6.5× object, 57% smaller bundle, 2× faster TS compile, 100× fewer tsc instantiations. Major API shifts: top-level format validators (`z.email()`, `z.url()`, `z.uuid()`) for tree-shaking; unified `error` parameter replaces `required_error` / `invalid_type_error` / `errorMap`. Codemod available: `npx @zod/codemod`. Covers schema design, RHF + zodResolver integration, API response validation, split server/client env schemas (security-critical for `NEXT_PUBLIC_*`), reusable schemas, transforms, and Next.js Server Actions. Mentions Valibot/ArkType when bundle/inference cost matters. Invoke at any trust boundary."
 ---
 
-# Zod Validation — Runtime Type Safety
+# Zod 4 — Runtime Type Safety (2026)
 
-**ALWAYS use Zod for form validation, API responses, and data boundaries.**
+**ALWAYS use Zod 4 for form validation, API responses, env vars, server actions.**
 
-## Why Zod
+## Why Zod 4 (stable since August 2025)
 
-- Runtime validation (TypeScript types disappear at runtime)
-- Auto-infer TypeScript types from schemas
-- Works with React Hook Form, tRPC, Next.js Server Actions
-- Single source of truth: schema → type → validation
+- **14× faster** string parsing, **7×** array, **6.5×** object
+- **57% smaller** core bundle
+- **~2× faster** TS compilation on large schemas; **100× fewer** tsc instantiations
+- Ecosystem locked in: tRPC, Drizzle, React Hook Form, OpenAPI generators
+- 15M+ weekly downloads — the de-facto standard
+
+### When to consider an alternative
+
+| Situation | Tool |
+|---|---|
+| **Bundle size** is critical (edge functions, embeds) | **Valibot** — sub-1KB simple schemas |
+| You want **faster TS check** in giant codebases | **Valibot** (~18× faster type-check vs Zod 4) |
+| You like TS-syntax string schemas | **ArkType** |
+| Mainstream ecosystem + maturity | **Zod 4** ✅ |
+
+## Migration v3 → v4
+
+```bash
+npx @zod/codemod --transform v3-to-v4 ./src
+```
+
+The two breaking changes you'll see most:
+
+### 1. Top-level format validators (tree-shaking)
+
+```tsx
+// v3 (works in v4 but not tree-shakable)
+z.string().email().min(5);
+
+// v4 — recommended
+z.email();
+z.url();
+z.uuid();
+z.iso.datetime();         // ISO-8601
+z.iso.date();
+z.cuid2();
+z.ipv4();
+z.ipv6();
+z.base64();
+z.jwt();
+```
+
+### 2. Unified `error` parameter
+
+```tsx
+// v3 — three different parameters
+z.string({
+  required_error: "Required",
+  invalid_type_error: "Must be a string",
+  errorMap: ({ code }) => ({ message: code === "too_small" ? "Too short" : "Invalid" }),
+});
+
+// v4 — one parameter, string or function
+z.string({
+  error: (issue) => issue.code === "too_small" ? "Too short" : "Required",
+});
+// Or just a string:
+z.string({ error: "Name is required" });
+```
 
 ## Core Patterns
 
-### Schema Definition
+### Schema definition
 
 ```tsx
 import { z } from 'zod';
 
-// Define schema
 const UserSchema = z.object({
-  name: z.string().min(2, 'Name must be at least 2 characters'),
-  email: z.string().email('Invalid email address'),
-  age: z.number().min(18, 'Must be 18+').max(120),
-  role: z.enum(['admin', 'user', 'moderator']),
-  bio: z.string().max(500).optional(),
-  tags: z.array(z.string()).min(1, 'At least one tag required'),
+  name:     z.string().min(2, "Name must be at least 2 characters"),
+  email:    z.email({ error: "Enter a valid email" }),       // v4 top-level
+  age:      z.number().min(18, "Must be 18+").max(120),
+  role:     z.enum(["admin", "user", "moderator"]),
+  bio:      z.string().max(500).optional(),
+  tags:     z.array(z.string()).min(1, "At least one tag required"),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
 
-// Infer type from schema (SINGLE SOURCE OF TRUTH)
+// SINGLE SOURCE OF TRUTH — schema → type
 type User = z.infer<typeof UserSchema>;
 ```
 
-### Form Validation (React Hook Form + Zod)
+### Form Validation (React Hook Form + Zod 4)
 
 ```tsx
 import { useForm } from 'react-hook-form';
@@ -44,7 +99,7 @@ import { zodResolver } from '@hookform/resolvers/zod';
 
 const CreateUserSchema = z.object({
   name: z.string().min(2),
-  email: z.string().email(),
+  email: z.email(),                                   // v4 top-level
   password: z.string().min(8, 'Password must be at least 8 characters'),
   confirmPassword: z.string(),
 }).refine((data) => data.password === data.confirmPassword, {
@@ -150,24 +205,47 @@ export const clientEnv = ClientEnvSchema.parse({
 
 **Rule:** If a variable contains a key, secret, token, or password, it MUST be in `ServerEnvSchema` without `NEXT_PUBLIC_` prefix.
 
-### Reusable Schemas
+### Reusable Schemas (Zod 4 top-level)
 
 ```tsx
-// Shared between frontend and backend
-// schemas/user.ts
-
-export const EmailSchema = z.string().email().toLowerCase().trim();
+// schemas/common.ts — shared between frontend and backend
+export const EmailSchema    = z.email().transform(v => v.toLowerCase().trim());
 export const PasswordSchema = z.string().min(8).max(128);
-export const UUIDSchema = z.string().uuid();
+export const UUIDSchema     = z.uuid();
+export const URLSchema      = z.url();
+export const ISODateSchema  = z.iso.datetime();
+
 export const PaginationSchema = z.object({
-  page: z.coerce.number().min(1).default(1),
+  page:  z.coerce.number().min(1).default(1),
   limit: z.coerce.number().min(1).max(100).default(20),
 });
 
 export const DateRangeSchema = z.object({
   from: z.coerce.date(),
-  to: z.coerce.date(),
-}).refine((d) => d.to > d.from, 'End date must be after start date');
+  to:   z.coerce.date(),
+}).refine(d => d.to > d.from, "End date must be after start date");
+```
+
+### Discriminated unions (polymorphic payloads)
+
+```tsx
+const PaymentSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("card"), last4: z.string().length(4) }),
+  z.object({ type: z.literal("pix"),  key:   z.string() }),
+  z.object({ type: z.literal("boleto"), barcode: z.string() }),
+]);
+type Payment = z.infer<typeof PaymentSchema>;
+```
+
+### Branded types — distinguish IDs at the type level
+
+```tsx
+const UserIdSchema = z.uuid().brand<"UserId">();
+type UserId = z.infer<typeof UserIdSchema>;
+
+function getUser(id: UserId) { /* … */ }
+getUser("not a uuid");                  // ❌ type error
+getUser(UserIdSchema.parse(input));     // ✅
 ```
 
 ### Transform & Preprocess
@@ -253,20 +331,64 @@ export function LeadForm() {
 }
 ```
 
+## Use with React 19 Actions + `useActionState`
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { z } from "zod";
+
+const Schema = z.object({
+  email:    z.email(),
+  password: z.string().min(8),
+});
+
+async function loginAction(_prev: { error: string | null }, formData: FormData) {
+  const parsed = Schema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) return { error: parsed.error.issues[0].message };
+  return await loginRequest(parsed.data);
+}
+
+export function LoginForm() {
+  const [state, action, pending] = useActionState(loginAction, { error: null });
+  return (
+    <form action={action}>
+      <input name="email" type="email" />
+      <input name="password" type="password" />
+      {state.error && <p className="text-destructive">{state.error}</p>}
+      <button disabled={pending}>{pending ? "Signing in…" : "Sign in"}</button>
+    </form>
+  );
+}
+```
+
 ## FORBIDDEN
 
 | Don't | Do |
 |---|---|
-| Trust API responses blindly | `Schema.parse(response)` |
-| Manual `if/else` validation | Zod schema |
+| Trust API responses blindly | `Schema.parse(response)` (or `safeParse` for soft fail) |
+| Manual `if/else` validation | Zod schema (single source of truth) |
 | Duplicate types + validation | `z.infer<typeof Schema>` |
 | `any` or `unknown` without validation | Parse with Zod first |
-| Validate only on server | Validate on BOTH client + server |
+| Validate only on server | Validate on BOTH client and server |
+| `z.string().email()` in v4 | `z.email()` (tree-shakable, top-level) |
+| `required_error` / `invalid_type_error` / `errorMap` (v3) | Unified `error` parameter (v4) |
+| Dump secrets into `NEXT_PUBLIC_*` | Server-only `ServerEnvSchema`; client gets only public keys |
+| Re-implement common formats (URL, UUID, datetime, JWT) | `z.url()`, `z.uuid()`, `z.iso.datetime()`, `z.jwt()` |
 
 ## Rules
 
 1. **SINGLE SOURCE OF TRUTH** — schema defines type AND validation
-2. **VALIDATE AT BOUNDARIES** — forms, API responses, env vars
-3. **SAFE PARSE FOR UI** — `safeParse()` for user-facing, `parse()` for internal
-4. **SHARED SCHEMAS** — same schema on frontend and backend
-5. **TRANSFORM DATA** — clean/normalize during validation, not after
+2. **VALIDATE AT BOUNDARIES** — forms, API responses, env vars, queue messages
+3. **SAFE PARSE FOR UI** — `safeParse()` for user-facing forms, `parse()` for internal/trusted
+4. **SHARED SCHEMAS** — same schema on frontend and backend (workspace package)
+5. **TRANSFORM DURING VALIDATION** — `.toLowerCase()`, `.trim()`, `.transform(...)` happen as part of `parse`, not afterwards
+6. **PREFER TOP-LEVEL FORMAT VALIDATORS** in v4 — better tree-shaking + clearer intent
+
+## See Also
+
+- `react-patterns` v2 — `useActionState`, `useOptimistic`, `use()` hook
+- `react-ui-patterns` v2 — RHF + Zod + TanStack Query patterns
+- `shadcn-ui` v2 — `<Form>` component built on RHF + Zod
+- `_shared/skills/security-baseline` v2 — input validation as defense layer
+- `_shared/skills/openapi-design` v2 — schemas → OpenAPI 3.2

package/stacks/frontend/react-api/skills/axios-laravel-api/SKILL.md

@@ -1,11 +1,7 @@
 ---
 name: axios-laravel-api
-version: 1.0.0
-description: Axios HTTP client for Laravel 12 + Sanctum SPA — `withCredentials`,
-  `withXSRFToken`, `/sanctum/csrf-cookie` flow, and `401/403/419/422/5xx`
-  interceptors. Use when wiring a React (or any SPA) frontend to a Laravel
-  cookie-authenticated JSON API. Pairs with `laravel-api-architecture` and
-  `react-api-standards`.
+version: 2.0.0
+description: "Axios HTTP client for Laravel 12 + Sanctum SPA in React 19 (Tailwind v4) projects. `withCredentials: true` + `withXSRFToken: true` + `/sanctum/csrf-cookie` priming flow, plus a single response interceptor that handles 401 (logout), 403 (forbidden toast), 419 (CSRF stale → re-prime + retry once), 422 (validation errors surfaced to RHF), 5xx (toast + log). Pairs with `laravel-api-architecture` (backend) and `react-api-standards` (frontend conventions). 2026 polish: Zod 4 response validation at the boundary, TanStack Query v5 `signal` threading for cancellation, React 19 forms via `useActionState` for client-side mutations. Invoke when wiring or auditing the API client, login flow, or CSRF/cookie configuration."
 ---
 
 # Axios + Laravel Sanctum SPA Client

package/stacks/frontend/react-api/skills/react-api-standards/SKILL.md

@@ -1,25 +1,23 @@
 ---
 name: react-api-standards
-version: 1.0.0
-description: React 19 + Vite + Axios standards for a Laravel-backed JSON API SPA
-  — Page shell + skeleton, async data via `api.get`, form 422 binding, route
-  catch-all, no Inertia. Use for any new React page in a Laravel + Sanctum SPA
-  project. Pairs with `axios-laravel-api` and `laravel-api-architecture`.
+version: 2.0.0
+description: "React 19 + Vite 6 + Axios standards for a Laravel-backed JSON API SPA. Page shell + skeleton-first paint, async data via `api.get`, 422 validation binding to React Hook Form, protected-route + catch-all routing, NO Inertia. Pairs with `axios-laravel-api` (HTTP client) and `laravel-api-architecture` (backend). 2026 polish: TanStack Query v5 (`isPending` semantics + `signal` threading), Zod 4 (`z.email()`/`z.url()` top-level), `useOptimistic` for instant feedback, `useActionState` for form submissions, `useFormStatus` to wire Submit buttons without prop drilling. Tailwind v4 with `@theme` and OKLCH tokens. Invoke for any new page, layout, or component in a Laravel + Sanctum SPA."
 ---
 
-# React 19 API-First Standards (Laravel + Axios)
+# React 19 API-First Standards (Laravel + Axios) — 2026
 
 **ALWAYS invoke when creating React pages, components, or layouts in a project
 that uses a Laravel JSON API as backend (NOT Inertia.js).**
 
 ## Version Requirements
 
-- **React >= 19** — MANDATORY (`useActionState`, `useOptimistic`, `use`)
-- **Vite >= 5** with `@vitejs/plugin-react`
-- **TailwindCSS >= 4**
-- **Axios >= 1.6** (for `withXSRFToken` support)
-- **TanStack Query >= 5** (recommended for cached lists/details)
-- **react-router-dom >= 6** (client-side routing)
+- **React ≥ 19.0** — MANDATORY (`useActionState`, `useOptimistic`, `useFormStatus`, `use()`)
+- **Vite ≥ 6** with `@vitejs/plugin-react`
+- **TailwindCSS ≥ 4** (CSS-first `@theme`, Oxide engine)
+- **Axios ≥ 1.7** (for `withXSRFToken` and modern interceptor types)
+- **TanStack Query ≥ 5** — `isPending` (no data yet) vs `isFetching` (any in-flight); thread `signal` through `queryFn`
+- **Zod ≥ 4** — top-level `z.email()`/`z.url()` for tree-shaking
+- **react-router-dom ≥ 7** (`<RouterProvider>` + data routers)
 
 ## Folder Structure
 

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

@@ -1,14 +1,14 @@
 ---
 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.
+version: 2.0.0
+description: "Python (FastAPI / Django / Flask) overlay on top of _shared/security-baseline v2 (OWASP Top 10:2025). Production-grade hardening: security headers via Starlette middleware and SECURE_* settings, strict CORS allowlist, rate limiting (slowapi / django-ratelimit), HttpOnly+Secure+SameSite cookies, JWT with algorithms=[ALG] pinning + jti for revocation using PyJWT (python-jose is unmaintained as of 2025), CSRF built-in for Django and double-submit cookie for FastAPI, Pydantic V2 extra='forbid' against mass-assignment, file-upload magic-byte sniffing, Argon2id passwords, parameterised SQL/ORM. Cross-references 2025-A03 (Software Supply Chain Failures) and 2025-A10 (Mishandling Exceptional Conditions)."
 ---
 
-# API Security — Python
+# API Security — Python (FastAPI / Django / Flask)
 
 **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.
+> Stack-specific overlay on top of `_shared/skills/security-baseline` v2 (OWASP Top 10:2025). The shared skill defines §A01–§A10 anchors; this one wires the Python equivalents.
 
 ## Layered Defense
 
@@ -136,13 +136,16 @@ response.set_cookie(
 
 ## 5. JWT / OAuth2 — FastAPI
 
+> **Library choice (2026):** Use **PyJWT** (`pyjwt[crypto]`) or **authlib** for OAuth2/OIDC flows. `python-jose` has been effectively unmaintained since 2024 and should be removed from dependencies. For the resource-server side that just verifies tokens, PyJWT is enough.
+
 ```python
 from datetime import datetime, timedelta, timezone
-from jose import jwt, JWTError
 import os, uuid
+import jwt
+from jwt import InvalidTokenError
 
 SECRET = os.environ["JWT_SECRET"]
-ALG = "HS256"
+ALG = "HS256"                    # use RS256/EdDSA when verifying tokens minted elsewhere
 
 def issue_access_token(user_id: str, role: str) -> str:
     now = datetime.now(timezone.utc)
@@ -151,8 +154,11 @@ def issue_access_token(user_id: str, role: str) -> str:
             "sub": user_id,
             "role": role,
             "iat": now,
+            "nbf": now,
             "exp": now + timedelta(minutes=15),
             "jti": str(uuid.uuid4()),
+            "iss": os.environ["JWT_ISSUER"],
+            "aud": os.environ["JWT_AUDIENCE"],
         },
         SECRET,
         algorithm=ALG,
@@ -160,9 +166,18 @@ def issue_access_token(user_id: str, role: str) -> str:
 
 async def current_user(token: str = Depends(oauth2_scheme)) -> User:
     try:
-        payload = jwt.decode(token, SECRET, algorithms=[ALG])  # pin algorithm
-    except JWTError:
+        payload = jwt.decode(
+            token,
+            SECRET,
+            algorithms=[ALG],                # pin — never accept "alg: none"
+            audience=os.environ["JWT_AUDIENCE"],
+            issuer=os.environ["JWT_ISSUER"],
+            options={"require": ["exp", "iat", "sub", "jti"]},
+        )
+    except InvalidTokenError:
         raise HTTPException(401, "Invalid token")
+    if await is_revoked(payload["jti"]):     # check revocation list (Redis set)
+        raise HTTPException(401, "Token revoked")
     user = await User.get_or_none(id=payload["sub"])
     if not user:
         raise HTTPException(401, "User not found")
@@ -170,9 +185,11 @@ async def current_user(token: str = Depends(oauth2_scheme)) -> 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.
+- Access tokens ≤ 15 min. Refresh tokens: rotate on use, store **hash** in DB, revocable.
+- Pin `algorithms=[ALG]`. Never accept `alg: none` or omit the kwarg (confusion attack).
+- Always validate `aud` and `iss` when present.
+- Include `jti` and check a revocation set for sensitive scopes.
+- Store JWTs in **HttpOnly+Secure+SameSite cookies**, not `localStorage` (XSS exfiltration).
 
 ---
 
@@ -280,6 +297,91 @@ user = await User.get(id=user_id)                   # Tortoise / SQLAlchemy / Dj
 
 ---
 
+## 11. Outbound calls — SSRF guard (OWASP 2025 still relevant)
+
+SSRF was demoted from a top-level OWASP category in the 2025 list but remains in scope. Any time you fetch a URL the user controls (preview cards, webhooks, image proxies), validate the destination:
+
+```python
+import ipaddress
+import socket
+from urllib.parse import urlparse
+import httpx
+
+PRIVATE = ipaddress.collapse_addresses([
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("169.254.0.0/16"),     # link-local + AWS metadata
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("::1/128"),
+])
+
+def safe_url(url: str) -> str:
+    p = urlparse(url)
+    if p.scheme not in {"http", "https"}:
+        raise ValueError("scheme")
+    host = p.hostname
+    if not host:
+        raise ValueError("host")
+    for fam, _, _, _, sockaddr in socket.getaddrinfo(host, None):
+        ip = ipaddress.ip_address(sockaddr[0])
+        if any(ip in net for net in PRIVATE):
+            raise ValueError("private")
+    return url
+
+async def fetch_user_url(url: str):
+    safe_url(url)
+    async with httpx.AsyncClient(timeout=10.0, follow_redirects=False) as c:
+        return await c.get(url)
+```
+
+Disable redirect-following or re-validate every hop — otherwise an attacker can redirect from a public IP to `169.254.169.254` (cloud metadata).
+
+## 12. OWASP 2025 deltas — Python specifics
+
+### §A03 — Software Supply Chain Failures (NEW in 2025)
+
+```toml
+# pyproject.toml — pin everything; uv produces a deterministic lockfile
+[project]
+dependencies = ["fastapi>=0.115,<0.116", "pydantic>=2.6,<3"]
+
+[tool.uv]
+dev-dependencies = ["pip-audit>=2.7", "ruff>=0.5"]
+```
+
+```bash
+# Lock + verify in CI
+uv lock --check                              # fails if lockfile drifted
+uv export --format requirements-txt --no-dev | pip-audit -r /dev/stdin --strict
+```
+
+- Use `uv` (or Poetry) to produce a deterministic lockfile; never `pip install` without one in production.
+- Run `pip-audit` (PyPA) **and** subscribe to GHSA advisories for your deps.
+- Pin GitHub Actions by SHA, not tag — see `_shared/skills/secrets-management`.
+
+### §A10 — Mishandling Exceptional Conditions (NEW in 2025)
+
+```python
+# WRONG — silently swallows everything, including programming bugs
+try:
+    user = await get_user(id)
+except Exception:
+    user = None
+
+# CORRECT — narrow except + log + propagate or translate
+try:
+    user = await get_user(id)
+except UserNotFoundError:
+    raise HTTPException(404, "user not found")
+except DatabaseUnavailableError as e:
+    logger.exception("db-down", extra={"user_id": id})
+    raise HTTPException(503, "service unavailable") from e
+# Programming errors (KeyError, TypeError) are NOT caught — let the global handler 500 + log
+```
+
+Bare `except Exception:` (or worse, `except:`) is now an explicit OWASP pattern to flag. Use `logger.exception()` so the stack trace lands in logs, return a **generic** message to the client, never the original exception text.
+
 ## Endpoint Checklist
 
 - [ ] `Depends(current_user)` for protected routes
@@ -306,7 +408,8 @@ user = await User.get(id=user_id)                   # Tortoise / SQLAlchemy / Dj
 
 ## See Also
 
-- `security-baseline` — OWASP Top 10
-- `secrets-management` — env vars, rotation
-- `pydantic-validation` — schema patterns
-- `observability` — structured logs without PII
+- `_shared/skills/security-baseline` v2 — OWASP Top 10:2025 (§A01–§A10 anchors)
+- `_shared/skills/secrets-management` v2 — OIDC federation, gitleaks 3-layer, SOPS+age
+- `_shared/skills/observability` v2 — structured logs without PII, GenAI semconv 1.41+
+- `pydantic-validation` v2 — `extra="forbid"` against mass-assignment
+- `fastapi-patterns` v2 — lifespan, DI, exception handlers