torusguard 0.9.2

package/skills/torusguard/payload/references/express-security.md

@@ -0,0 +1,103 @@
+# Express Security Guide
+
+## When to use
+
+Load during audits of Node.js Express APIs serving web or mobile clients.
+
+**Related rules:** TG-INPUT-001, TG-INPUT-002, TG-AUTH-003, TG-AUTH-004, TG-RATE-001, TG-PLATFORM-001 … TG-PLATFORM-004
+
+## Checklist
+
+- [ ] Helmet or equivalent security headers (TG-PLATFORM-002)
+- [ ] CORS explicit allowlist — never `*` with credentials (TG-PLATFORM-001)
+- [ ] `express.json({ limit: '100kb' })` or appropriate cap (TG-PLATFORM-004)
+- [ ] Zod/Joi validation on every mutating route (TG-INPUT-001)
+- [ ] Parameterized SQL or ORM — no concatenation (TG-INPUT-002)
+- [ ] Rate limits on login, reset, OTP (TG-RATE-001)
+- [ ] Central error handler — generic client messages (TG-PLATFORM-003)
+- [ ] Secure cookie flags for sessions (TG-AUTH-004)
+- [ ] Ownership middleware on resource routes (TG-AUTH-003)
+
+## Baseline server setup
+
+```javascript
+import express from 'express';
+import helmet from 'helmet';
+import cors from 'cors';
+import rateLimit from 'express-rate-limit';
+
+const app = express();
+const allowedOrigins = ['https://app.example.com'];
+
+app.use(helmet());
+app.use(cors({
+  origin(origin, cb) {
+    if (!origin || allowedOrigins.includes(origin)) cb(null, true);
+    else cb(new Error('Not allowed by CORS'));
+  },
+  credentials: true,
+}));
+app.use(express.json({ limit: '100kb' }));
+
+const loginLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 5,
+  standardHeaders: true,
+  message: { error: 'Too many attempts' },
+});
+app.post('/api/login', loginLimiter, loginHandler);
+```
+
+## Validation middleware
+
+```javascript
+import { z } from 'zod';
+
+function validate(schema) {
+  return (req, res, next) => {
+    const parsed = schema.safeParse({ body: req.body, query: req.query, params: req.params });
+    if (!parsed.success) return res.status(400).json({ error: 'Invalid input' });
+    req.validated = parsed.data;
+    next();
+  };
+}
+```
+
+## Ownership middleware
+
+```javascript
+async function requireOrderOwner(req, res, next) {
+  const order = await db.order.findUnique({ where: { id: req.params.id } });
+  if (!order || order.userId !== req.user.id) {
+    return res.status(403).json({ error: 'Forbidden' });
+  }
+  req.order = order;
+  next();
+}
+```
+
+## Error handler
+
+```javascript
+app.use((err, req, res, next) => {
+  console.error({ err, requestId: req.id });
+  res.status(err.status || 500).json({
+    error: process.env.NODE_ENV === 'production' ? 'Internal server error' : err.message,
+  });
+});
+```
+
+## Distributed rate limiting
+
+Use Redis or similar shared store in multi-instance production — in-memory limiters alone are insufficient (TG-RATE-001).
+
+## Manual review
+
+- Enumerate all `app.use` order (auth before routes)
+- Verify upload routes have size/type/auth checks
+- Run dependency audit before deploy
+
+## Related documentation
+
+- [rules/TG-PLATFORM-001-wildcard-cors-with-credentials.md](../rules/TG-PLATFORM-001-wildcard-cors-with-credentials.md)
+- [skills/TorusGuard/references/platform-hardening.md](../skills/TorusGuard/references/platform-hardening.md)

package/skills/torusguard/payload/references/fastapi-security.md

@@ -0,0 +1,20 @@
+# TorusGuard Skill Reference: FastAPI Security
+
+> **Loaded When:** Project uses `fastapi` dependencies or imports.
+
+---
+
+## 🛡️ Key Inspection Areas & Rules
+
+### 1. Route Authorization & Dependencies
+* `TG-AUTH-001` / `TG-AUTH-003`: Verify protected routes include security dependencies (`Depends(get_current_user)`).
+* `TG-AUTH-007`: In route handlers taking numeric/UUID path parameters (e.g. `profile_id`, `invoice_id`), verify that database queries filter by the authenticated user's ID.
+
+### 2. Request Models & Mass Assignment
+* `TG-AUTH-006`: Check that endpoints accept structured Pydantic `BaseModel` classes rather than raw `dict`, `Body(...)`, or unpacking `**payload` directly into ORM entities.
+
+### 3. Outbound Requests & SSRF
+* `TG-SSRF-001`: Inspect endpoints that fetch external URLs via `httpx` or `requests`. Verify scheme validation and private IP address filtering.
+
+### 4. Webhook Integrity
+* `TG-WEBHOOK-001`: In webhook endpoints, verify HMAC signature validation using `await request.body()` (raw bytes) before JSON parsing.

package/skills/torusguard/payload/references/firebase-security.md

@@ -0,0 +1,78 @@
+# Firebase Security Guide
+
+## When to use
+
+Load during audits of Firebase Auth, Firestore, Realtime Database, or Storage.
+
+**Related rules:** TG-DB-003, TG-AUTH-002, TG-AUTH-003, TG-SEC-002
+
+## Key distinction
+
+| SDK | Where | Purpose |
+|-----|-------|---------|
+| **Firebase client SDK** | Browser/mobile | User-facing ops constrained by Security Rules |
+| **Firebase Admin SDK** | Server only | Privileged operations — never in frontend |
+
+## Checklist
+
+- [ ] Admin SDK credentials server-only (TG-DB-003)
+- [ ] Firestore/RTDB Security Rules deployed and tested
+- [ ] Storage rules restrict paths by `request.auth.uid`
+- [ ] Client rules do not trust client-supplied ownership fields alone
+- [ ] Custom claims used for roles verified server-side for sensitive ops
+- [ ] Emulator tests for rule changes
+
+## Client SDK (safe with rules)
+
+```javascript
+import { initializeApp } from 'firebase/app';
+import { getFirestore, doc, getDoc } from 'firebase/firestore';
+
+const app = initializeApp(firebaseConfig); // public config is OK
+const db = getFirestore(app);
+```
+
+## Firestore rules example
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+    match /orders/{orderId} {
+      allow read: if request.auth != null
+        && resource.data.ownerId == request.auth.uid;
+    }
+  }
+}
+```
+
+## Admin SDK (server only)
+
+```javascript
+// functions or server/index.js — never in React src/
+import admin from 'firebase-admin';
+admin.initializeApp({ credential: admin.credential.cert(serviceAccount) });
+```
+
+Never commit service account JSON; use environment or secret manager (TG-SEC-001, TG-SEC-003).
+
+## Manual rules review checklist
+
+1. Default-deny: are unmatched paths blocked?
+2. Can users read/write other users' documents by guessing IDs?
+3. Are admin collections inaccessible to normal users?
+4. Do Storage paths include user ID validation?
+5. Run emulator tests for allow/deny cases
+
+## Auth token validation
+
+For custom backends verifying Firebase ID tokens, use Admin SDK `verifyIdToken` — do not decode JWT without signature verification.
+
+## Related documentation
+
+- [rules/TG-DB-003-frontend-admin-sdk.md](../rules/TG-DB-003-frontend-admin-sdk.md)
+- [rules/TG-AUTH-003-missing-object-authorization.md](../rules/TG-AUTH-003-missing-object-authorization.md)
+- [skills/TorusGuard/references/frontend-no-db.md](../skills/TorusGuard/references/frontend-no-db.md)

package/skills/torusguard/payload/references/flask-security.md

@@ -0,0 +1,20 @@
+# TorusGuard Skill Reference: Flask Security
+
+> **Loaded When:** Project uses `flask` dependencies or imports.
+
+---
+
+## 🛡️ Key Inspection Areas & Rules
+
+### 1. Secret Key & Cookie Configuration
+* `TG-SEC-001`: Inspect `app.config['SECRET_KEY']`. Flag hardcoded string literals.
+* `TG-PLATFORM-003`: Verify `app.debug = False` in production configs.
+
+### 2. Authorization & Ownership (IDOR)
+* `TG-AUTH-007`: In route handlers querying database models by route variables (e.g. `<int:id>`), verify that the query filters by `current_user.id`.
+
+### 3. CSRF Protection
+* `TG-CSRF-001`: Verify that cookie-authenticated web forms initialize `flask_wtf.CSRFProtect`.
+
+### 4. File Uploads
+* `TG-INPUT-004`: Ensure uploaded filenames are filtered using `secure_filename()` and validate against an extension whitelist.

package/skills/torusguard/payload/references/nextjs-security.md

@@ -0,0 +1,96 @@
+# Next.js Security Guide
+
+## When to use
+
+Load during audits of Next.js App Router or Pages Router applications.
+
+**Related rules:** TG-SEC-002, TG-DB-003, TG-AUTH-002, TG-AUTH-003, TG-CLIENT-001, TG-PLATFORM-002
+
+## Server vs client boundary
+
+| Location | Can use secrets? | Can access DB? |
+|----------|------------------|----------------|
+| Server Components, Route Handlers, Server Actions | Yes (env without `NEXT_PUBLIC_`) | Yes (server SDK) |
+| Client Components (`'use client'`) | No | No |
+
+Never import server-only modules (Prisma, `pg`, Firebase Admin, service-role Supabase) into Client Components.
+
+## Checklist
+
+- [ ] No `NEXT_PUBLIC_*` variables hold secrets (TG-SEC-002)
+- [ ] Route handlers and Server Actions validate input and authorize users
+- [ ] `productionBrowserSourceMaps: false` in production
+- [ ] Cookie sessions use httpOnly, Secure, SameSite (TG-AUTH-004)
+- [ ] CSRF considered for cookie-authenticated mutations
+- [ ] Sensitive data not over-cached in public CDN routes
+- [ ] Security headers via `next.config` or middleware/Helmet on custom server
+
+## Environment variables
+
+```env
+# Server-only
+DATABASE_URL=postgresql://...
+JWT_SECRET=...
+
+# Client-safe
+NEXT_PUBLIC_API_URL=https://api.example.com
+```
+
+## Route handler pattern
+
+```typescript
+// app/api/orders/[id]/route.ts
+import { z } from 'zod';
+import { getSession } from '@/lib/session';
+import { db } from '@/lib/db';
+
+const paramsSchema = z.object({ id: z.string().uuid() });
+
+export async function GET(req: Request, { params }: { params: { id: string } }) {
+  const session = await getSession();
+  if (!session) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const parsed = paramsSchema.safeParse(params);
+  if (!parsed.success) return Response.json({ error: 'Invalid input' }, { status: 400 });
+
+  const order = await db.order.findFirst({
+    where: { id: parsed.data.id, userId: session.userId },
+  });
+  if (!order) return Response.json({ error: 'Not found' }, { status: 404 });
+
+  return Response.json(order);
+}
+```
+
+## Server Actions
+
+Validate and authorize at the start of every Server Action. Do not trust hidden form fields for `role` or `userId`.
+
+## Source maps
+
+```javascript
+// next.config.js
+const nextConfig = {
+  productionBrowserSourceMaps: false,
+};
+export default nextConfig;
+```
+
+## CSRF and sessions
+
+When using cookie-based auth with Server Actions or form POSTs, verify Origin/Referer or use CSRF tokens for state-changing requests.
+
+## Cache and privacy
+
+Avoid caching personalized responses at CDN edge unless intentionally public. Review `fetch` cache options and `revalidate` settings for user-specific data.
+
+## Manual review
+
+- Trace every `'use client'` file for accidental secret imports
+- Test IDOR on dynamic `[id]` routes (TG-AUTH-003)
+- Review middleware auth coverage
+
+## Related documentation
+
+- [rules/TG-AUTH-003-missing-object-authorization.md](../rules/TG-AUTH-003-missing-object-authorization.md)
+- [guides/express-security.md](express-security.md) (custom server)

package/skills/torusguard/payload/references/react-vite-security.md

@@ -0,0 +1,97 @@
+# React + Vite Security Guide
+
+## When to use
+
+Load during audits of React + Vite frontends with a separate or proxied API backend.
+
+**Related rules:** TG-SEC-002, TG-DB-001, TG-DB-002, TG-AUTH-002, TG-CLIENT-001, TG-CLIENT-002, TG-INPUT-003
+
+## Core truth: the browser bundle is public
+
+If the browser receives JavaScript, users can read it in DevTools, Sources, and network tabs. TorusGuard cannot block Inspect Element. Never put secrets, database credentials, or authorization decisions only in client code.
+
+## Checklist
+
+- [ ] No secrets in `VITE_*` environment variables
+- [ ] No SQL, ORM, or DB driver imports in `src/`
+- [ ] Private data fetched only through authenticated API calls
+- [ ] `build.sourcemap: false` for production (TG-CLIENT-001)
+- [ ] No `console.log` of tokens, users, or config in production paths
+- [ ] Route guards are UX only — server enforces authorization (TG-AUTH-002)
+- [ ] User HTML rendered as text unless sanitized (TG-INPUT-003)
+- [ ] CSP configured at hosting/API layer where applicable
+
+## Environment variables
+
+Only intentionally public values belong in Vite client env:
+
+```env
+# .env.example — safe for client
+VITE_API_URL=http://localhost:3001
+VITE_APP_NAME=MyApp
+
+# NEVER prefix secrets with VITE_
+# JWT_SECRET, DATABASE_URL, STRIPE_SECRET_KEY → server only
+```
+
+```javascript
+// vite.config.js — disable public production source maps
+export default defineConfig({
+  build: { sourcemap: false },
+  server: {
+    proxy: { '/api': 'http://localhost:3001' },
+  },
+});
+```
+
+## Data access pattern
+
+```javascript
+// client/src/api/users.js — safe
+export async function fetchMyProfile() {
+  const res = await fetch('/api/users/me', { credentials: 'include' });
+  if (!res.ok) throw new Error('Unauthorized');
+  return res.json();
+}
+```
+
+Never construct SQL or import `pg`, `@prisma/client`, or Supabase service-role client in `src/`.
+
+## Client route guards
+
+```jsx
+// UX redirect only — NOT security
+function AdminRoute({ children }) {
+  const { user } = useAuth();
+  if (!user?.role) return <Navigate to="/login" />;
+  return children;
+}
+```
+
+Every admin action must still fail on the server without proper role checks.
+
+## Safe rendering
+
+```jsx
+// Safe — React escapes text by default
+<p>{user.bio}</p>
+
+// High risk — only with trusted/sanitized HTML
+<div dangerouslySetInnerHTML={{ __html: sanitizedHtml }} />
+```
+
+## CSP considerations
+
+Define CSP at the reverse proxy or Express/Next layer. Account for Vite dev server in development; tighten for production with explicit `script-src`, `connect-src`, and `img-src` origins.
+
+## Manual review
+
+- Verify API endpoints enforce auth for every sensitive client call
+- Confirm no secret accidentally added to `import.meta.env` usage
+- Review third-party scripts loaded in `index.html`
+
+## Related documentation
+
+- [rules/TG-SEC-002-public-environment-secrets.md](../rules/TG-SEC-002-public-environment-secrets.md)
+- [rules/TG-CLIENT-001-public-production-source-maps.md](../rules/TG-CLIENT-001-public-production-source-maps.md)
+- [skills/TorusGuard/references/client-code-exposure.md](../skills/TorusGuard/references/client-code-exposure.md)

package/skills/torusguard/payload/references/sqlalchemy-security.md

@@ -0,0 +1,16 @@
+# TorusGuard Skill Reference: SQLAlchemy Security
+
+> **Loaded When:** Project uses `sqlalchemy` dependencies or imports.
+
+---
+
+## 🛡️ Key Inspection Areas & Rules
+
+### 1. SQL Injection in Raw Query Clauses
+* `TG-INPUT-003`: Search for `text(f"...")`, `text("..." + ...)`, or `.format()` inside `text()` constructs. Ensure parameter mapping `text("... WHERE col = :val")` is used.
+
+### 2. Tenant Scoping & Object Ownership
+* `TG-AUTH-007`: Verify queries on tenant-isolated tables include tenant/user ID predicates in `.filter()` or `.filter_by()`.
+
+### 3. Mass Assignment via Bulk Updates
+* `TG-AUTH-006`: Inspect `.update(dict)` calls to ensure input dictionaries are filtered against permitted field allowlists.

package/skills/torusguard/payload/references/supabase-security.md

@@ -0,0 +1,84 @@
+# Supabase Security Guide
+
+## When to use
+
+Load during audits of applications using Supabase Auth, Database, or Storage.
+
+**Related rules:** TG-DB-002, TG-DB-003, TG-AUTH-003, TG-SEC-002
+
+## Key distinction
+
+| Key | Where | Purpose |
+|-----|-------|---------|
+| **anon (public) key** | Browser OK | Client SDK with RLS enforced |
+| **service-role key** | Server only | Bypasses RLS — never in frontend |
+
+Violating this mapping triggers TG-DB-002 (Critical) and TG-DB-003 (Critical).
+
+## Checklist
+
+- [ ] Service-role key only in server/edge functions
+- [ ] RLS enabled on every table exposed to client
+- [ ] Policies verify `auth.uid()` ownership or role
+- [ ] Storage bucket policies restrict read/write by user
+- [ ] No sensitive logic relying only on client-side filters
+- [ ] Server-only admin actions use service-role in trusted environment
+
+## Browser client (safe)
+
+```javascript
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY
+);
+```
+
+## Server admin (safe)
+
+```javascript
+// server/admin.js — never import in client bundle
+import { createClient } from '@supabase/supabase-js';
+
+const admin = createClient(
+  process.env.SUPABASE_URL,
+  process.env.SUPABASE_SERVICE_ROLE_KEY
+);
+```
+
+## RLS policy example
+
+```sql
+ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users read own profile"
+  ON profiles FOR SELECT
+  USING (auth.uid() = user_id);
+
+CREATE POLICY "Users update own profile"
+  ON profiles FOR UPDATE
+  USING (auth.uid() = user_id);
+```
+
+## Manual RLS review checklist
+
+For each table reachable from the browser:
+
+1. Is RLS enabled?
+2. Does SELECT policy prevent cross-user reads?
+3. Do INSERT/UPDATE/DELETE policies verify ownership?
+4. Are admin-only tables blocked for anon/authenticated roles?
+5. Test with two user sessions — User A must not read User B rows
+
+Document review date in project `SECURITY.md`.
+
+## Storage
+
+Apply bucket policies mirroring database ownership. Do not use public buckets for private user files without signed URL strategy.
+
+## Related documentation
+
+- [rules/TG-DB-002-privileged-database-credential.md](../rules/TG-DB-002-privileged-database-credential.md)
+- [rules/TG-DB-003-frontend-admin-sdk.md](../rules/TG-DB-003-frontend-admin-sdk.md)
+- [skills/TorusGuard/references/frontend-no-db.md](../skills/TorusGuard/references/frontend-no-db.md)

package/skills/torusguard/payload/rules/README.md

@@ -0,0 +1,62 @@
+# TorusGuard Security Rule Catalog & Activation System
+
+This directory manages the active and custom security rules enforced by TorusGuard.
+
+---
+
+## 1. Rule Architecture & Taxonomy
+
+TorusGuard security rules follow a canonical identifier pattern: `TG-<CATEGORY>-<NUMBER>`.
+
+| Category Prefix | Domain Area | Focus & Vulnerability Classes |
+| :--- | :--- | :--- |
+| `TG-AUTH` | Authentication & Authorization | Missing tenant scoping, client-only route guards, session cookie flags, insecure password resets |
+| `TG-INPUT` | Input Validation & Injection | SQL injection, unsafe HTML/template rendering, unvalidated file uploads, path traversal |
+| `TG-SEC` | Secrets & Configuration | Hardcoded API keys, tracked `.env` files, sensitive logging, exposed cloud credentials |
+| `TG-DB` | Database & ORM Security | Frontend direct DB access, admin SDK exposure, missing multi-tenant query isolation |
+| `TG-CLIENT` | Frontend & Client Bundles | Public production source maps, sensitive secrets embedded in client build assets |
+| `TG-RATE` | Rate Limiting & Resource Abuse | Unlimited auth endpoints, unbounded pagination, excessive resource consumption |
+| `TG-PLATFORM` | Platform & Gateway Hardening | Wildcard CORS with credentials, missing security headers, exposed stack traces |
+| `TG-SSRF` | Outbound Requests & SSRF | Unvalidated HTTP client destinations, metadata IP access, internal network probing |
+| `TG-SUPPLY` | Dependency & Supply Chain | Unpinned dependencies, known CVEs, malicious dependency confusion risks |
+
+---
+
+## 2. Active Rules System (`rules/active/`)
+
+When you run `/torusguard init`, TorusGuard automatically inspects your project stack and activates relevant rules in `rules/active/`.
+
+- **Universal Rules:** Always activated (`TG-SEC-*`, `TG-INPUT-*`, `TG-AUTH-*`).
+- **Framework-Specific Rules:**
+  - Python / Django: `TG-DB-004`, `TG-RATE-001`, `TG-PLATFORM-*`.
+  - Next.js / React: `TG-CLIENT-*`, `TG-PLATFORM-001`, `TG-AUTH-002`.
+  - API / Node.js: `TG-INPUT-001`, `TG-SSRF-001`, `TG-RATE-002`.
+
+---
+
+## 3. Creating Custom Rules
+
+You can add custom rules directly into this directory or configure a custom path in `.torusguard/config/torusguard.json`:
+
+```markdown
+# TG-CUSTOM-001: Require Organization UUID on All Tenant Queries
+
+**Severity:** High  
+**Category:** authentication-authorization  
+**Confidence Base:** 80  
+
+### Vulnerability Pattern
+Ensure every database query on multi-tenant models filters explicitly by `org_id` or `tenant_id`.
+
+### Unsafe Pattern
+```python
+# Unsafe: Queries tenant data globally without org predicate
+TenantRecord.objects.filter(status="active")
+```
+
+### Safe Pattern
+```python
+# Safe: Scoped to requesting organization
+TenantRecord.objects.filter(org_id=request.user.org_id, status="active")
+```
+```