coding-os 0.3.2__py3-none-any.whl

core/skills/auth-patterns/references/sessions-vs-jwt.md

@@ -0,0 +1,230 @@
+# Server Sessions vs JWTs — Decision + Implementation
+
+The choice that shapes every other auth decision. Read once; refer to the table when you're tempted to switch mid-design.
+
+## The Honest Comparison
+
+| Concern | Server sessions (opaque token) | JWT (signed claims) |
+|---|---|---|
+| **Storage** | DB row per session | None server-side (or blocklist) |
+| **Read cost / request** | DB lookup or Redis hit | Verify signature (~µs) |
+| **Revocation** | Instant (`UPDATE sessions SET revoked_at = NOW()`) | Hard — short TTL or blocklist |
+| **Token size** | ~32 bytes opaque | 200-1000 bytes |
+| **Logout from all devices** | `DELETE WHERE user_id = X` | Per-user `iat_min` revocation epoch |
+| **Multi-service trust** | Need shared session store / call-back endpoint | Self-contained — verify signature |
+| **Audit / observability** | Easy — sessions table is the source of truth | Harder — need usage tracking |
+| **Mobile-friendly** | Yes — opaque token in Keychain | Yes — opaque token in Keychain |
+| **Browser-friendly** | Cookies + CSRF defense | Cookies (CSRF), header (XSS), localStorage (XSS+disk) |
+| **Attack surface on theft** | One DB lookup → revoked | Valid until expiry; revocation hard |
+| **Cross-domain SSO** | Hard (cookies are origin-scoped) | Easier (just verify the token) |
+| **Operational complexity** | Low (one DB) | Medium (key rotation, JWKS, blocklist) |
+
+## Decision Tree
+
+```
+Single trust domain (one product, one team's services)?
+├─ Yes → Server sessions
+│   └─ Need to call other internal services with user identity?
+│       └─ Yes → Mint short-lived JWT at the API gateway / business backend.
+│                The CLIENT never sees a JWT.
+│
+└─ No (multiple distinct trust domains, third-party callers)
+    └─ JWT — short-lived, signed, with key rotation
+        └─ Need revocation? → Blocklist or `iat_min` per-user epoch.
+```
+
+## Server Session Implementation
+
+### Schema
+
+```sql
+CREATE TABLE sessions (
+    id              TEXT        PRIMARY KEY,           -- public token (e.g. "ses_8h2k...")
+    token_hash      TEXT        NOT NULL,              -- SHA-256 of id (defense-in-depth: DB dump = no usable tokens)
+    user_id         TEXT        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    family_id       TEXT        NOT NULL,              -- shared with refresh tokens for theft detection
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_seen_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    expires_at      TIMESTAMPTZ NOT NULL,
+    revoked_at      TIMESTAMPTZ,                       -- NULL while active
+    user_agent      TEXT,
+    ip              INET,
+    scopes          TEXT[]      NOT NULL DEFAULT '{}'  -- granted scopes
+);
+
+CREATE INDEX idx_sessions_user_active ON sessions(user_id) WHERE revoked_at IS NULL;
+CREATE INDEX idx_sessions_token_hash ON sessions(token_hash);
+
+-- Sweep job (hourly): delete sessions revoked > 30 days ago.
+```
+
+The token format: `ses_<32 random chars from URL-safe alphabet>`. The DB stores `SHA-256(token)` and only validates by hash — even a full DB dump doesn't yield usable tokens.
+
+### Verify Middleware (Go + Fiber)
+
+```go
+func RequireSession(store SessionStore) fiber.Handler {
+    return func(c fiber.Ctx) error {
+        token := bearerToken(c.Get("Authorization"))
+        if token == "" {
+            return apperr.Unauthenticated(c, "missing_token", "")
+        }
+
+        hash := sha256Hex(token)
+        sess, err := store.LookupActive(c.Context(), hash)
+        if err != nil {
+            return apperr.Unauthenticated(c, "invalid_token", "")
+        }
+
+        // Update last_seen async (don't block the request).
+        go store.TouchAsync(sess.ID)
+
+        c.Locals("user_id", sess.UserID)
+        c.Locals("scopes", sess.Scopes)
+        return c.Next()
+    }
+}
+```
+
+Cache hot sessions in Redis with a short TTL (60s) to absorb the read load. Cache invalidation = delete by ID on revoke.
+
+### Verify Middleware (Python + FastAPI)
+
+```python
+from fastapi import Depends, HTTPException, Header
+
+async def require_session(
+    authorization: str = Header(...),
+    store: SessionStore = Depends(get_session_store),
+) -> Actor:
+    token = bearer_token(authorization)
+    if not token:
+        raise HTTPException(401, detail="missing_token")
+    sess = await store.lookup_active(sha256_hex(token))
+    if not sess:
+        raise HTTPException(401, detail="invalid_token")
+    asyncio.create_task(store.touch(sess.id))
+    return Actor(user_id=sess.user_id, scopes=sess.scopes)
+```
+
+## JWT Implementation (Internal Service-to-Service)
+
+When the Go backend calls the Python AI adapter, it mints a short-lived JWT:
+
+```go
+import "github.com/golang-jwt/jwt/v5"
+
+type ServiceClaims struct {
+    Scope []string `json:"scope"`
+    jwt.RegisteredClaims
+}
+
+func MintServiceToken(privKey ed25519.PrivateKey, kid, userID string, scopes []string) (string, error) {
+    now := time.Now()
+    claims := ServiceClaims{
+        Scope: scopes,
+        RegisteredClaims: jwt.RegisteredClaims{
+            Subject:   userID,
+            Issuer:    "business-api",
+            Audience:  jwt.ClaimStrings{"ai-adapter"},
+            IssuedAt:  jwt.NewNumericDate(now),
+            ExpiresAt: jwt.NewNumericDate(now.Add(5 * time.Minute)),
+            NotBefore: jwt.NewNumericDate(now.Add(-30 * time.Second)),  // clock skew
+            ID:        uuid.NewString(),                                 // jti for replay tracking
+        },
+    }
+    tok := jwt.NewWithClaims(jwt.SigningMethodEdDSA, claims)
+    tok.Header["kid"] = kid
+    return tok.SignedString(privKey)
+}
+```
+
+Verify (Python side):
+
+```python
+import jwt
+import httpx
+from cachetools import TTLCache
+
+JWKS_CACHE: TTLCache = TTLCache(maxsize=4, ttl=600)
+
+async def get_jwks(issuer: str) -> dict:
+    if issuer in JWKS_CACHE:
+        return JWKS_CACHE[issuer]
+    async with httpx.AsyncClient(timeout=5) as client:
+        resp = await client.get(f"{issuer}/.well-known/jwks.json")
+        resp.raise_for_status()
+    jwks = resp.json()
+    JWKS_CACHE[issuer] = jwks
+    return jwks
+
+
+async def verify_service_token(token: str) -> dict:
+    unverified = jwt.get_unverified_header(token)
+    kid = unverified.get("kid")
+    if not kid:
+        raise jwt.InvalidTokenError("missing kid")
+
+    jwks = await get_jwks("https://business-api.app.com")
+    key = next((k for k in jwks["keys"] if k["kid"] == kid), None)
+    if not key:
+        raise jwt.InvalidTokenError("unknown kid")
+
+    public_key = jwt.algorithms.OKPAlgorithm.from_jwk(key)
+    payload = jwt.decode(
+        token,
+        public_key,
+        algorithms=["EdDSA"],
+        audience="ai-adapter",
+        issuer="https://business-api.app.com",
+        leeway=30,                               # clock skew tolerance
+        options={"require": ["sub", "iat", "exp", "aud", "iss"]},
+    )
+    return payload  # {"sub": "usr_…", "scope": [...], ...}
+```
+
+### Algorithm Selection — 2026
+
+- **EdDSA (Ed25519)** — first choice. Small keys, fast, no parameter footguns.
+- **RS256** — broadly compatible; pick if EdDSA support is missing in any consumer library.
+- **ES256** — fine alternative; popular in WebAuthn ecosystem.
+- **HS256** — only for symmetric scenarios where the verifier is the issuer. NEVER share the secret across trust boundaries.
+- **`alg: none`** — every library MUST reject. If yours doesn't, switch libraries.
+
+### Key Rotation
+
+```
+business-api/
+  /.well-known/jwks.json   →  { keys: [ {kid:"2026-04", ...}, {kid:"2026-03", ...} ] }
+```
+
+- Mint with current `kid`.
+- Publish current + previous in JWKS for the lifetime of the longest-lived token.
+- Rotate quarterly (or after any suspected key compromise).
+- Verifiers cache JWKS for 10 min, refresh on `kid` miss.
+
+## Hybrid Pattern (This Project)
+
+```
+Client (RN) ──[opaque session]──► Go API
+                                     │
+                                     │ Mint JWT { sub: user_id, scope, exp:5m, kid }
+                                     ▼
+                                FastAPI AI adapter (verifies via JWKS)
+```
+
+Best of both:
+
+- Client always uses opaque sessions (revocable, simple to wipe).
+- Service-to-service uses short JWTs (stateless, scoped, no extra DB hop on the AI adapter).
+- AI adapter never sees the long-lived session token, so a compromise of the AI service doesn't expose user sessions.
+
+## What NOT to Do
+
+1. **Long-lived JWT as the only client credential** — leaks last forever.
+2. **Session ID in URL query string** — leaks via referrers, logs, browser history.
+3. **JWT in localStorage** for browser apps — XSS reads it.
+4. **Stateless JWT for the user-facing API** without a path to revocation.
+5. **Storing JWT secret in env vars accessible to client-side build** — pretty obvious mistake but seen in practice.
+6. **Using HS256 across services owned by different teams** — shared secret = no trust boundary.
+7. **Validating only signature, not `aud`/`iss`/`exp`** — token from one context valid in another.

core/skills/auth-patterns/scripts/cookie-flag-check.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Audit Set-Cookie usage for missing security flags.
+
+Scans Python (Django + FastAPI + raw Werkzeug/Flask), TypeScript (Express,
+Next.js Route Handlers, Hono), and Go (Fiber, stdlib net/http) source
+files for cookie-setting calls without Secure/HttpOnly/SameSite.
+
+Usage:
+  python cookie-flag-check.py [paths...]
+  python cookie-flag-check.py --json [paths...]
+
+Exit code 1 if any finding.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+# Lightweight regex audit — not a full parser. Trade-off: occasional false
+# positive worth the simplicity. Run with --json in CI; review findings.
+
+# Python: response.set_cookie(...), Cookie('...'), HttpResponse(...).set_cookie
+PY_COOKIE_PATTERNS = [
+    re.compile(r"\.set_cookie\s*\("),
+    re.compile(r"response\.cookies\s*\["),
+    re.compile(r"morsel\s*=\s*Morsel"),
+]
+PY_REQUIRED_FLAGS = ["httponly", "secure", "samesite"]
+
+# TypeScript / JS: res.cookie(...), res.setHeader('Set-Cookie', ...), cookies().set(...)
+TS_COOKIE_PATTERNS = [
+    re.compile(r"\bres\.cookie\s*\("),
+    re.compile(r"\bsetHeader\s*\(\s*['\"]Set-Cookie['\"]"),
+    re.compile(r"\bcookies\(\)\.set\s*\("),
+]
+TS_REQUIRED_FLAGS = ["httpOnly", "secure", "sameSite"]
+
+# Go: c.Cookie(&fiber.Cookie{...}), http.SetCookie(...)
+GO_COOKIE_PATTERNS = [
+    re.compile(r"\bc\.Cookie\s*\(&fiber\.Cookie"),
+    re.compile(r"\bhttp\.SetCookie\s*\("),
+]
+GO_REQUIRED_FLAGS = ["HttpOnly", "Secure", "SameSite"]
+
+
+@dataclass
+class Finding:
+    path: str
+    line: int
+    missing: list[str]
+    snippet: str
+
+
+def _audit_block(text: str, start: int, required: list[str], window: int = 12) -> list[str]:
+    """From `start`, scan up to `window` lines forward; return missing flags."""
+    lines = text.splitlines()
+    end = min(len(lines), start + window)
+    block = "\n".join(lines[start:end]).lower()
+    missing = [f for f in required if f.lower() not in block]
+    return missing
+
+
+def audit_file(path: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return findings
+
+    ext = path.suffix.lower()
+    if ext in {".py"}:
+        patterns, required = PY_COOKIE_PATTERNS, PY_REQUIRED_FLAGS
+    elif ext in {".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs"}:
+        patterns, required = TS_COOKIE_PATTERNS, TS_REQUIRED_FLAGS
+    elif ext in {".go"}:
+        patterns, required = GO_COOKIE_PATTERNS, GO_REQUIRED_FLAGS
+    else:
+        return findings
+
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        for pat in patterns:
+            if pat.search(line):
+                missing = _audit_block(text, i, required)
+                if missing:
+                    findings.append(
+                        Finding(
+                            path=str(path),
+                            line=i + 1,
+                            missing=missing,
+                            snippet=line.strip()[:120],
+                        )
+                    )
+                break  # one finding per line max
+    return findings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("paths", nargs="*", default=["."])
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument(
+        "--exclude", default=".venv,venv,node_modules,.build,dist,__pycache__,.git,vendor"
+    )
+    args = parser.parse_args()
+
+    excluded = set(s for s in args.exclude.split(",") if s)
+    target_files: list[Path] = []
+    for root in args.paths:
+        p = Path(root)
+        if p.is_file():
+            target_files.append(p)
+        elif p.is_dir():
+            for f in p.rglob("*"):
+                if not f.is_file():
+                    continue
+                if any(part in excluded for part in f.parts):
+                    continue
+                if f.suffix.lower() in {".py", ".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".go"}:
+                    target_files.append(f)
+
+    findings: list[Finding] = []
+    for f in target_files:
+        findings.extend(audit_file(f))
+
+    if args.json:
+        json.dump([asdict(x) for x in findings], sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        if not findings:
+            print(f"[cookie-flag-check] OK: {len(target_files)} files scanned, no findings.")
+        else:
+            print(f"[cookie-flag-check] FOUND {len(findings)} finding(s):\n")
+            for f in findings:
+                print(f"  {f.path}:{f.line}  missing={','.join(f.missing)}  | {f.snippet}")
+
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

core/skills/backend-fundamentals/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: backend-fundamentals
+tier: layer
+domain: [backend]
+description: Stack-agnostic backend patterns. Use when writing or modifying any server-side code (HTTP handler, DB query, background job, auth/middleware, webhook) regardless of language or framework. Covers services/selectors split, idempotency, error envelopes, migration discipline, N+1 avoidance, scale-aware design, auth guardrails, and logging hygiene.
+globs: "backend/**/*"
+paths: ["backend/**/*"]
+context: fork
+depends_on:
+  - clean-code
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Edit
+  - Write
+last_reviewed: "2026-05-11"
+
+---
+
+# Backend Fundamentals — Stack-Agnostic Patterns
+
+Universal guidance that holds for Django, FastAPI, Go (stdlib + Fiber), Rails, NestJS, Spring, and any other server-side framework. Framework-specific layering (DRF ViewSets, Pydantic `Depends`, Fiber middleware chain) lives in the stack-specific skill that `depends_on: [backend-fundamentals]`.
+
+Loaded automatically when `enforce-skill.sh` routes a file under `backend/` that matches a stack skill.
+
+## 0. Scale mindset (think before writing)
+
+Every handler, query, and API must be written as if it will be called by 1,000 concurrent users on a 50M-row table. Before writing:
+
+- **How many rows does this touch?** Unknown → run `EXPLAIN ANALYZE` or ask.
+- **How many callers at once?** Single-user admin page vs. public endpoint changes everything.
+- **Where's the bottleneck?** DB index miss · network hop · CPU work.
+- **What's the latency budget?** Default P99 < 500 ms; surface the number in the PR description.
+- **What happens if step 3 of 5 fails?** Transactions · idempotency key · compensating action.
+
+Code that works on 10 rows but collapses on 10 M is a production incident waiting for traffic. Correct answer to "will this scale?" is a number, not "yes".
+
+## 1. Service / selector split
+
+Business logic lives in **services** (write path — mutates state, encapsulates a transaction). Read-only DB queries live in **selectors** (pure functions, cached when possible). Controllers / views / handlers only:
+
+1. Parse and validate the request.
+2. Call a service or selector.
+3. Shape the response.
+
+No ORM calls in controllers. No business rules in serializers. No DB writes in selectors. This split makes unit testing trivial (mock the service boundary) and keeps transaction boundaries visible.
+
+## 2. Standard response envelope
+
+Every handler returns **one** of:
+
+```json
+{ "ok": true,  "data":  <T> }
+{ "ok": false, "error": { "code": "<UPPER_SNAKE>", "message": "<human>", "retryable": true|false } }
+```
+
+Error codes come from a **project-level registry** (list every code in one file, e.g. `backend/errors.py` or `docs/api-contracts/error-codes.md`). Never invent codes on the fly — if a new case doesn't fit an existing code, add the new code to the registry first, then reference it.
+
+`retryable` tells the client whether retry helps: transient/infrastructure errors `true`, validation/permission/not_found `false`. Prevents infinite retry loops on deterministic failures.
+
+## 3. Idempotency — every state-changing call
+
+Every endpoint that mutates state MUST accept (or derive) an idempotency key:
+
+- Webhook → key = `<provider>:<event_id>` (Stripe, Square, GitHub, ...).
+- Internal service call → key = `sha256(normalized_input_json)`.
+- User-initiated → key = `Idempotency-Key` header (RFC 8594-style).
+
+Persist the key **before** side effects. Three states: `processing`, `processed`, `failed`. If the key already exists as `processing`/`processed`, return the stored response — do NOT re-apply the operation. Multi-table writes MUST run inside a single transaction; on rollback, also roll back the idempotency row.
+
+Without this discipline: double-charge, duplicate fulfillment, duplicate email sends. It's the single most common production bug on payment / webhook paths.
+
+## 4. N+1 query prevention
+
+If you see a `for` loop with a DB call inside, it's wrong:
+
+```python
+# WRONG — 1 query + N queries
+for order in orders:
+    order.customer = db.get_customer(order.customer_id)
+
+# RIGHT — 2 queries total
+customer_ids = {o.customer_id for o in orders}
+customers = db.get_customers_by_ids(customer_ids)
+customer_by_id = {c.id: c for c in customers}
+for order in orders:
+    order.customer = customer_by_id[order.customer_id]
+
+# OR use ORM join/prefetch:
+orders = Order.objects.select_related("customer")  # Django
+orders = db.query(Order).options(joinedload(Order.customer))  # SQLAlchemy
+```
+
+Rule: before a loop over DB rows, materialize the join batch. ORMs have `select_related` / `prefetch_related` / `joinedload` / `Preload` — learn the one for your stack.
+
+## 5. Indexes on every WHERE / JOIN / ORDER BY
+
+If a column appears in `WHERE`, `JOIN`, or `ORDER BY` on a table expected to have > 10K rows, it MUST have an index. Verify with `EXPLAIN ANALYZE` on the real DB (not a fresh dev DB with 10 rows — fake stats lie).
+
+For composite predicates, the index column order matters: most-selective-first for equality, then range. E.g., `WHERE user_id = ? AND created_at > ?` wants `(user_id, created_at)`, not `(created_at, user_id)`.
+
+No "full table scan" on production-sized tables is acceptable. Index maintenance cost ≪ scan cost once data grows.
+
+## 6. Pagination — never return all rows
+
+Offset pagination is fine for small admin lists (LIMIT + OFFSET up to page 50). **Cursor-based pagination is required** when:
+
+- Result set > 10K rows, or
+- Deep pages are common (page 500+), or
+- Inserts happen concurrently (offset drifts).
+
+Cursor = opaque token encoding the last-seen sort key (e.g., base64-encoded `(created_at, id)` tuple). Return `next_cursor` in the response envelope; client echoes it back as `cursor=` in the next call.
+
+Hard cap: MAX 100 rows per page. Client-supplied `limit` > 100 is rejected as `VALIDATION_ERROR`.
+
+## 7. Transactions — atomicity for multi-step writes
+
+Any operation that writes to ≥ 2 tables (or inserts to 1 and updates another) MUST run inside one transaction:
+
+```python
+with db.transaction():
+    idempotency_row = create_idempotency_row(key, status="processing")
+    order = create_order(payload)
+    inventory_reserve(order.items)
+    # If any step raises, ALL rollback — no partial state.
+    idempotency_row.status = "processed"
+```
+
+Transactions should be **short**. Never hold an open transaction while calling an external API (Stripe, email provider, S3). Pattern: (1) short DB tx to stage, (2) release connection, (3) external call, (4) short DB tx to commit. Long-held transactions exhaust connection pools under load.
+
+## 8. Migrations — append-only, forward-safe
+
+- **Append-only.** New tables / columns → new migration. Never edit a past migration that's been deployed.
+- **Forward-safe.** Every migration must be applicable to a database where previous migrations ran. Destructive changes (drop column, rename) need a two-step dance: deploy code that doesn't use the column → migration drops it → deploy next release.
+- **Idempotent.** `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, `INSERT ... ON CONFLICT DO NOTHING`. Re-applying a migration on the same DB must be safe.
+- **Reversible when practical.** Every migration file has a `down` / `revert` section. Data migrations are the exception — document why revert is manual.
+- **No secrets in migrations.** API keys, JWTs, service-role credentials go via vault / dashboard / env. Document the manual step as a comment in the closest related migration.
+
+## 9. Auth / permissions — default deny
+
+- **Default deny.** No endpoint is public unless explicitly marked. Framework defaults (Django's `IsAuthenticated`, FastAPI's `Depends(get_current_user)`, Fiber's auth middleware) go at the router/app level, exemptions are the ones with decorators.
+- **Identity vs. authorization.** "Who is this request?" is authentication (JWT / session). "Can they do X to Y?" is authorization (RBAC / row-level). Keep them in separate layers — a service method receives `user_id` and re-checks permissions, doesn't trust the controller.
+- **Row-level security.** For multi-tenant data, every query that touches a tenant-scoped table MUST filter by tenant_id in WHERE. The DB layer (RLS in Postgres, filter in ORM manager) is the last line, not the only line.
+- **Re-verify before destructive ops.** Email-change, password-reset, account-delete: require recent re-auth (timestamp on the session < 5 min old) regardless of existing login.
+
+## 10. Logging — step-numbered, redacted, correlatable
+
+```python
+log.info("🟣 STEP 1 — validating input", extra={"trace_id": trace_id, "user_id": user_id})
+log.info("✅ STEP 1 OK — 3 items")
+log.info("🟣 STEP 2 — charging gateway")
+log.info("🔥 FATAL — gateway error %s", err_code, extra={"trace_id": trace_id})
+```
+
+- Every log line carries `trace_id` (from request header or generated) so a support ticket can be traced end-to-end.
+- **Redact PII and secrets.** Allow-list of fields to log; everything else masked. Never log raw request/response JSON on payment or auth paths.
+- Emoji step markers (🟣 start, ✅ ok, ⚠️ warn, 🔥 fatal) make grep easier and reduce the temptation to write `print("got here")` debug code.
+
+## 11. External calls — timeouts, retries, circuit breakers
+
+Any call to a system you don't control (payment gateway, email provider, S3, third-party API):
+
+- **Timeouts.** Hard timeout < your endpoint's budget. Never "default" timeout (which is often 30–60 s on HTTP libs). Pick a number and justify it.
+- **Retries.** Only on idempotent operations. Exponential backoff with jitter. Cap at 3 attempts. Non-idempotent call failures propagate to the caller as `transient` with `retryable=true` so the caller decides.
+- **Circuit breaker.** If > N failures in window W, trip the breaker and fast-fail for cool-down period C. Libraries: `pybreaker`, `hystrix`, `gobreaker`. Don't hand-roll.
+- **Never hold DB connection during external call.** Release, call, reacquire.
+
+## 12. Async jobs & background work
+
+Any operation > 2 s (email, heavy compute, external aggregation, report generation) MUST be queued:
+
+- **Don't make the user wait.** Return `202 Accepted` with a job id; client polls or subscribes for result.
+- **Job contract:** a job is a pure function of its payload. Jobs MUST be idempotent (same payload replayed → same result).
+- **Dead letter queue.** After N retries, job moves to DLQ with full context. Alert on DLQ size > 0.
+- **Observability.** Per-job `trace_id` propagates from the enqueueing request; job logs and HTTP logs correlate.
+
+## 13. Audit events — high-value actions only
+
+Write an audit row for high-value actions: subscription create/change/cancel, payment success/failure, refund, admin override, security-sensitive config change. Schema:
+
+```
+id | occurred_at | actor_type | actor_id | action | subject_type | subject_id | summary | correlation_id
+```
+
+NEVER put secrets / PII in the summary. Audit rows are read by support, compliance, and ops — they must be safe to render on a dashboard.
+
+Anti-pattern: writing an audit row for every GET. Audit volume should correlate with state change, not traffic.
+
+## 14. Request validation — at the edge, once
+
+Validate once, at the HTTP boundary, using the framework's schema system (Pydantic, DRF Serializer, go-playground/validator, class-validator). Downstream services assume valid input.
+
+Reject on failure with `VALIDATION_ERROR` + field-level details so the client can show per-field feedback. No generic "invalid input" — list every failing field.
+
+## 15. Rate limiting — for public endpoints
+
+Any public endpoint (no auth, or user-auth without workspace scope) needs rate limiting. Strategy:
+
+- Per-IP for unauthenticated endpoints.
+- Per-user-id for authenticated endpoints.
+- Burst + sustained (e.g., 20 req / 1 min burst, 200 req / 1 hour sustained).
+- Return `429 Too Many Requests` with `Retry-After` header.
+
+Store counters in Redis or the framework's rate-limit module. Never in application memory (breaks under horizontal scale).
+
+## 16. Pre-commit / PR checklist
+
+Before opening a PR touching a backend file:
+
+- [ ] No N+1 (greped for `for .* in .*: .*db\.` / `for .* in .*: .*\.objects\.` patterns)
+- [ ] Response envelope consistent with project registry
+- [ ] Idempotency for mutation endpoints
+- [ ] Index verified via `EXPLAIN ANALYZE` on the matching table
+- [ ] Transaction wraps multi-table writes
+- [ ] Logs step-numbered, PII redacted, `trace_id` plumbed
+- [ ] External calls have explicit timeouts
+- [ ] Unit tests for service; integration test for the handler happy path + one error path
+- [ ] Migration is append-only and idempotent (if touched)
+
+## References
+
+Stack-specific specializations extend this skill via `depends_on: [backend-fundamentals]` — your project's stack skill (python-django / python-fastapi / go-patterns / go-fiber) is present when that stack is installed.
+
+## Tooling
+
+Flag framework/ORM leakage into domain/service code (keep the core framework-free):
+`python3 scripts/check_layering.py src/backend/services/*.py`
+
+## See also
+
+- [references/backend-patterns.md](references/backend-patterns.md) — layering, idempotency, errors, N+1, migrations.
+- [assets/backend-checklist.md](assets/backend-checklist.md) — the review gate.
+- [hexagonal-architecture](../hexagonal-architecture/SKILL.md) · [api-design](../api-design/SKILL.md) · [sql-authoring](../sql-authoring/SKILL.md).
+
+Universal principles from [clean-code](../clean-code/SKILL.md) still apply — this skill does not relax any of them.
+
+Cross-service code placement: promote a helper reused by a second service into `src/shared/<lang>/`, and route cross-language types through `src/shared/contracts/` only — see [clean-code](../clean-code/SKILL.md) § 7 and the `docs/engineering/project-anatomy.md` SSOT.

core/skills/backend-fundamentals/assets/backend-checklist.md

@@ -0,0 +1,27 @@
+<!-- domain:BACKEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# Backend Review Checklist
+
+Run when writing or reviewing server-side code.
+
+## Layering
+- [ ] Handler is thin: parse/validate → call service → format response.
+- [ ] Service holds the business rules, framework-free (no HTTP/request objects).
+- [ ] Repository is the only place with SQL/ORM.
+- [ ] `python3 scripts/check_layering.py <service/domain files>` → `clean`.
+
+## Correctness
+- [ ] State-changing operations are idempotent (key/upsert); webhooks tolerate duplicates.
+- [ ] Errors return one consistent envelope + correct status; no stack traces leaked.
+- [ ] Input validated at the boundary; output shape matches the contract.
+
+## Scale
+- [ ] No N+1 (batched/joined); every list endpoint paginated.
+- [ ] Queries are index-backed; assume the table grows 1000×.
+- [ ] Slow/retryable work offloaded to a queue, not the request thread.
+
+## Data
+- [ ] Migrations backward-compatible (expand→contract); no drop the live code reads.
+- [ ] No PII/secrets in logs (ids/redaction).
+
+## Verify
+- [ ] Matrix-targeted tests for what changed (test-discipline), error paths covered.