torusguard 1.0.0 → 1.3.1

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

@@ -1,62 +1,93 @@
-# 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")
-```
-```
+# TorusGuard Rule Catalog
+
+Stable rule IDs for TorusGuard v1.3.0. Each rule has a dedicated document in this directory.
+
+## Severity Definitions
+
+| Severity | Meaning |
+|----------|---------|
+| **Critical** | Secret exposure or flaw enabling immediate compromise of sensitive systems/data |
+| **High** | Exploitable weakness likely to expose or modify sensitive data, accounts, or privileged operations |
+| **Medium** | Important defense gap with meaningful but contextual impact |
+| **Low** | Hardening improvement or limited direct impact |
+| **Info** | Best-practice observation requiring human judgment |
+
+## Rule Index
+
+### Secrets and Configuration
+
+| ID | Title | Default Severity |
+|----|-------|------------------|
+| [TG-SEC-001](TG-SEC-001-hardcoded-secrets.md) | Hardcoded Secret | Critical |
+| [TG-SEC-002](TG-SEC-002-public-environment-secrets.md) | Sensitive Value in Public Environment Variable | Critical |
+| [TG-SEC-003](TG-SEC-003-tracked-env-file.md) | Tracked Environment File | High |
+| [TG-SEC-004](TG-SEC-004-sensitive-logging.md) | Sensitive Data Logging | Medium |
+
+### Frontend Database Exposure
+
+| ID | Title | Default Severity |
+|----|-------|------------------|
+| [TG-DB-001](TG-DB-001-frontend-database-query.md) | Database Query in Frontend Source | High |
+| [TG-DB-002](TG-DB-002-privileged-database-credential.md) | Privileged Database Credential in Browser Code | Critical |
+| [TG-DB-003](TG-DB-003-frontend-admin-sdk.md) | Frontend Admin SDK or Privileged Client | Critical |
+
+### Input and Injection
+
+| ID | Title | Default Severity |
+|----|-------|------------------|
+| [TG-INPUT-001](TG-INPUT-001-missing-server-validation.md) | Missing Server-Side Input Validation | High |
+| [TG-INPUT-002](TG-INPUT-002-raw-sql-concatenation.md) | Raw SQL Concatenation | Critical |
+| [TG-INPUT-003](TG-INPUT-003-unsafe-html-or-code-execution.md) | Unsafe HTML or Dynamic Code Execution | High |
+| [TG-INPUT-004](TG-INPUT-004-unrestricted-file-upload.md) | Unrestricted File Upload | High |
+
+### Authentication and Authorization
+
+| ID | Title | Default Severity |
+|----|-------|------------------|
+| [TG-AUTH-001](TG-AUTH-001-weak-password-storage.md) | Weak Password Storage | Critical |
+| [TG-AUTH-002](TG-AUTH-002-client-only-authorization.md) | Client-Only Authorization | High |
+| [TG-AUTH-003](TG-AUTH-003-missing-object-authorization.md) | Missing Object-Level Authorization (IDOR) | High |
+| [TG-AUTH-004](TG-AUTH-004-insecure-session-cookie.md) | Insecure Session Cookie | High |
+| [TG-AUTH-005](TG-AUTH-005-unsafe-password-reset.md) | Unsafe Password Reset or Account Recovery | High |
+
+### Rate Limiting and Resource Abuse
+
+| ID | Title | Default Severity |
+|----|-------|------------------|
+| [TG-RATE-001](TG-RATE-001-unlimited-auth-endpoint.md) | Unlimited Authentication Endpoint | High |
+| [TG-RATE-002](TG-RATE-002-unlimited-public-write-endpoint.md) | Unlimited Public Write or Expensive Endpoint | Medium |
+| [TG-RATE-003](TG-RATE-003-unbounded-resource-consumption.md) | Unbounded Resource Consumption | High |
+
+### Client Exposure
+
+| ID | Title | Default Severity |
+|----|-------|------------------|
+| [TG-CLIENT-001](TG-CLIENT-001-public-production-source-maps.md) | Public Production Source Maps | Medium |
+| [TG-CLIENT-002](TG-CLIENT-002-sensitive-client-bundle-content.md) | Sensitive Client Bundle Content | High |
+
+### Platform Hardening
+
+| ID | Title | Default Severity |
+|----|-------|------------------|
+| [TG-PLATFORM-001](TG-PLATFORM-001-wildcard-cors-with-credentials.md) | Wildcard CORS With Credentials | High |
+| [TG-PLATFORM-002](TG-PLATFORM-002-missing-security-headers.md) | Missing Security Headers | Medium |
+| [TG-PLATFORM-003](TG-PLATFORM-003-production-stack-trace-exposure.md) | Production Stack Trace or Internal Error Exposure | Medium |
+| [TG-PLATFORM-004](TG-PLATFORM-004-missing-request-size-limits.md) | Missing Request Size Limits | Medium |
+
+## Area Mapping for `/TorusGuard check`
+
+| Area | Rules |
+|------|-------|
+| `secrets` | TG-SEC-001 … TG-SEC-004 |
+| `database` | TG-DB-001 … TG-DB-003 |
+| `input` | TG-INPUT-001 … TG-INPUT-004 |
+| `auth` | TG-AUTH-001 … TG-AUTH-005 |
+| `rate-limit` | TG-RATE-001 … TG-RATE-003 |
+| `client` | TG-CLIENT-001 … TG-CLIENT-002 |
+| `platform` | TG-PLATFORM-001 … TG-PLATFORM-004 |
+
+## Related Documentation
+
+- Reference modules: `skills/TorusGuard/references/`
+- Framework guides: `guides/`
+- Example mappings: `examples/vulnerable-react-express/vulnerabilities.md`, `examples/hardened-react-express/fixes.md`

package/skills/torusguard/payload/rules/TG-AUTH-001-weak-password-storage.md

@@ -0,0 +1,103 @@
+# TG-AUTH-001: Weak Password Storage
+
+## Severity
+Critical
+
+## Applies To
+- User registration and login systems
+- Password reset and credential update flows
+- Legacy account import/migration jobs
+- Identity providers that store local credentials
+
+## Why It Matters
+Weak password storage enables catastrophic compromise when databases leak through attacks, backups, logs, or insider misuse.
+Plaintext, reversible encryption, or fast unsalted hashes let attackers recover passwords quickly and reuse them across services.
+Secure, adaptive hashing with per-password salt and optional pepper drastically reduces offline cracking feasibility.
+
+## What TorusGuard Looks For
+- Passwords stored as plaintext or encoded forms such as Base64.
+- Use of outdated fast hashes (`MD5`, `SHA1`, bare `SHA256`) for password storage.
+- Same hash value for identical passwords due to missing random salt.
+- Manual cryptography routines instead of vetted password hashing libraries.
+- Logging of raw passwords or hash inputs during authentication workflows.
+
+## Unsafe Example
+```js
+import crypto from "crypto";
+
+app.post("/api/register", async (req, res) => {
+  const email = req.body.email;
+  const password = req.body.password;
+
+  // Fast hash with no salt and no work factor
+  const passwordHash = crypto.createHash("sha256").update(password).digest("hex");
+
+  await db.user.create({
+    data: { email, password_hash: passwordHash }
+  });
+
+  res.json({ ok: true });
+});
+```
+
+## Safe Example
+```js
+import argon2 from "argon2";
+
+app.post("/api/register", async (req, res) => {
+  const email = String(req.body.email || "");
+  const password = String(req.body.password || "");
+
+  if (password.length < 12) {
+    return res.status(400).json({ ok: false, error: "Password too short" });
+  }
+
+  const hash = await argon2.hash(password, {
+    type: argon2.argon2id,
+    memoryCost: 19456,
+    timeCost: 2,
+    parallelism: 1
+  });
+
+  await db.user.create({
+    data: { email, password_hash: hash }
+  });
+
+  res.json({ ok: true });
+});
+
+app.post("/api/login", async (req, res) => {
+  const user = await db.user.findUnique({ where: { email: req.body.email } });
+  if (!user) return res.status(401).json({ ok: false });
+
+  const valid = await argon2.verify(user.password_hash, String(req.body.password || ""));
+  if (!valid) return res.status(401).json({ ok: false });
+
+  res.json({ ok: true });
+});
+```
+
+## Remediation
+1. Replace insecure password storage with Argon2id, bcrypt, or scrypt using recommended cost factors.
+2. Ensure each password hash includes a unique random salt (handled by modern libraries).
+3. Add optional application-level pepper stored in a secret manager, not in the database.
+4. Remove password values from logs, traces, analytics events, and error telemetry.
+5. Migrate existing hashes using rehash-on-login or controlled reset campaigns.
+6. Periodically tune work factors based on current hardware and latency targets.
+
+## Verification
+- Inspect stored credential records and confirm they use adaptive hash formats.
+- Verify identical passwords across test accounts produce different hash outputs.
+- Benchmark login flow to ensure configured cost factors are actually applied.
+- Attempt cracking tests on sample exported hashes to validate resistance assumptions.
+- Review codebase for direct use of fast hash APIs in authentication modules.
+
+## False Positives and Exceptions
+- One-way hashes for non-password tokens may look similar but are separate controls.
+- Temporary test fixtures can include static hashes only if isolated from production data paths.
+- External identity providers reduce local password handling scope but do not exempt backup credential paths.
+
+## Related Rules
+- [TG-AUTH-005](./TG-AUTH-005-unsafe-password-reset.md)
+- [TG-AUTH-004](./TG-AUTH-004-insecure-session-cookie.md)
+- [TG-INPUT-001](./TG-INPUT-001-missing-server-validation.md)

package/skills/torusguard/payload/rules/TG-AUTH-002-client-only-authorization.md

@@ -0,0 +1,85 @@
+# TG-AUTH-002: Client-Only Authorization
+
+## Severity
+High
+
+## Applies To
+- Single-page applications with protected routes
+- Mobile apps that hide privileged UI actions
+- APIs serving both user and admin clients
+- Feature-flagged operations with role constraints
+
+## Why It Matters
+Authorization enforced only in frontend code is not security control, because attackers can bypass the UI and call backend APIs directly.
+If server endpoints trust client-supplied role flags or hidden form fields, privilege escalation becomes trivial.
+Robust authorization must be verified on every sensitive backend action regardless of UI behavior.
+
+## What TorusGuard Looks For
+- Admin checks present in frontend components but absent in backend handlers.
+- API routes that trust `role`, `isAdmin`, or similar flags from request body/query.
+- Hidden buttons/menus used as the only barrier to privileged operations.
+- Use of local storage role values for security decisions.
+- Missing middleware or policy checks around destructive and high-impact endpoints.
+
+## Unsafe Example
+```js
+// Frontend blocks non-admin users from seeing delete button
+if (currentUser.role === "admin") {
+  showDeleteUserButton();
+}
+
+// Backend route does not verify authenticated role
+app.post("/api/admin/delete-user", async (req, res) => {
+  const targetUserId = req.body.userId;
+  await db.user.delete({ where: { id: targetUserId } });
+  res.json({ ok: true });
+});
+```
+
+## Safe Example
+```js
+function requireRole(...allowedRoles) {
+  return (req, res, next) => {
+    const role = req.auth?.role;
+    if (!allowedRoles.includes(role)) {
+      return res.status(403).json({ ok: false, error: "Forbidden" });
+    }
+    next();
+  };
+}
+
+app.post("/api/admin/delete-user", requireAuth, requireRole("admin"), async (req, res) => {
+  const targetUserId = String(req.body.userId || "");
+  if (!/^[a-f0-9-]{36}$/.test(targetUserId)) {
+    return res.status(400).json({ ok: false, error: "Invalid user id" });
+  }
+
+  await db.user.delete({ where: { id: targetUserId } });
+  res.json({ ok: true });
+});
+```
+
+## Remediation
+1. Enforce authorization checks on the server for every protected action and resource.
+2. Derive roles/permissions from authenticated server-side identity, not request payload flags.
+3. Implement centralized policy middleware to reduce inconsistent endpoint protection.
+4. Keep frontend role checks for UX only, never as the sole security mechanism.
+5. Add audit logging for privileged operations including actor, target, and outcome.
+6. Write regression tests that call endpoints directly without using the UI.
+
+## Verification
+- Call privileged endpoints with a non-admin token and verify consistent `403` responses.
+- Remove/hide frontend restrictions in browser devtools and confirm backend still blocks access.
+- Attempt sending forged `isAdmin: true` fields and verify they are ignored.
+- Inspect route registrations to ensure protected middleware is applied universally.
+- Review audit logs for denied authorization attempts.
+
+## False Positives and Exceptions
+- Public metadata endpoints may intentionally skip authorization if they contain no sensitive operations or data.
+- Early prototypes often rely on frontend checks; production deployment must not.
+- Internal admin APIs still require authorization controls unless isolated by strong network identity boundaries.
+
+## Related Rules
+- [TG-AUTH-003](./TG-AUTH-003-missing-object-authorization.md)
+- [TG-AUTH-004](./TG-AUTH-004-insecure-session-cookie.md)
+- [TG-INPUT-001](./TG-INPUT-001-missing-server-validation.md)

package/skills/torusguard/payload/rules/TG-AUTH-003-missing-object-authorization.md

@@ -0,0 +1,85 @@
+# TG-AUTH-003: Missing Object-Level Authorization (IDOR)
+
+## Severity
+High
+
+## Applies To
+- APIs that fetch or modify records by ID
+- File and document retrieval endpoints
+- Multi-tenant systems with organization-scoped data
+- Billing, messaging, and profile management resources
+
+## Why It Matters
+IDOR occurs when applications expose object identifiers but fail to verify that the requester is allowed to access that specific object.
+Attackers can enumerate or guess IDs to read, modify, or delete other users' resources without needing elevated roles.
+This creates severe confidentiality and integrity breaches, especially in multi-tenant products.
+
+## What TorusGuard Looks For
+- Endpoints reading `:id` or query IDs without ownership or tenant checks.
+- `findUnique`/`getById` calls that do not include current user or tenant constraints.
+- Access to files/records based solely on untrusted identifier parameters.
+- Sequential numeric IDs exposed in URLs with missing authorization guards.
+- Update/delete operations that authenticate user identity but skip object-level policy.
+
+## Unsafe Example
+```js
+app.get("/api/invoices/:invoiceId", requireAuth, async (req, res) => {
+  const invoiceId = req.params.invoiceId;
+
+  // Authenticated, but no check that invoice belongs to this user/tenant
+  const invoice = await db.invoice.findUnique({
+    where: { id: invoiceId }
+  });
+
+  if (!invoice) return res.status(404).json({ ok: false });
+  res.json({ ok: true, invoice });
+});
+```
+
+## Safe Example
+```js
+app.get("/api/invoices/:invoiceId", requireAuth, async (req, res) => {
+  const invoiceId = String(req.params.invoiceId || "");
+  const userId = req.auth.userId;
+  const tenantId = req.auth.tenantId;
+
+  const invoice = await db.invoice.findFirst({
+    where: {
+      id: invoiceId,
+      tenant_id: tenantId,
+      customer_user_id: userId
+    }
+  });
+
+  if (!invoice) {
+    return res.status(404).json({ ok: false, error: "Not found" });
+  }
+
+  res.json({ ok: true, invoice });
+});
+```
+
+## Remediation
+1. Apply object-level authorization checks on every read, update, and delete path.
+2. Scope data queries by authenticated user, tenant, account, or policy context.
+3. Centralize authorization policies so object checks are consistent across endpoints.
+4. Avoid exposing predictable identifiers when not required; consider opaque IDs.
+5. Log access denials and anomalous ID probing attempts for detection.
+6. Add tests that attempt cross-user and cross-tenant access with valid credentials.
+
+## Verification
+- Authenticate as User A and request User B resources by changing IDs.
+- Confirm unauthorized object access returns `404` or `403` consistently without data leakage.
+- Test update and delete endpoints, not only read endpoints.
+- Validate background jobs and export endpoints enforce tenant/object constraints too.
+- Inspect ORM/database queries for required ownership predicates.
+
+## False Positives and Exceptions
+- Public resources intentionally shared across tenants should be explicitly labeled and policy-reviewed.
+- Some administrative roles can access cross-tenant objects, but this must be explicit and auditable.
+- Random UUID usage alone does not remove need for object authorization.
+
+## Related Rules
+- [TG-AUTH-002](./TG-AUTH-002-client-only-authorization.md)
+- [TG-INPUT-001](./TG-INPUT-001-missing-server-validation.md)
+- [TG-INPUT-002](./TG-INPUT-002-raw-sql-concatenation.md)

package/skills/torusguard/payload/rules/TG-AUTH-004-insecure-session-cookie.md

@@ -0,0 +1,96 @@
+# TG-AUTH-004: Insecure Session Cookie Configuration
+
+## Severity
+High
+
+## Applies To
+- Web applications using cookie-based sessions
+- Authentication gateways and reverse proxies
+- Legacy apps migrating from token storage in local storage
+- SSO callback handlers setting auth cookies
+
+## Why It Matters
+Session cookies that lack secure attributes can be stolen, replayed, or manipulated by attackers.
+Missing `HttpOnly` enables JavaScript access during XSS, missing `Secure` exposes cookies over unencrypted transport, and weak `SameSite` settings increase CSRF risk.
+Improper domain/path/lifetime settings also expand token exposure across subdomains and long time windows.
+
+## What TorusGuard Looks For
+- Cookies set without `HttpOnly`, `Secure`, or explicit `SameSite`.
+- Session identifiers in URL parameters or local storage instead of hardened cookies.
+- Excessive cookie lifetime for sensitive sessions.
+- Broad cookie domain scopes (`.example.com`) without necessity.
+- Session rotation missing after login, privilege change, or password reset.
+
+## Unsafe Example
+```js
+app.post("/api/login", async (req, res) => {
+  const sessionId = await createSession(req.body.email, req.body.password);
+  if (!sessionId) return res.status(401).json({ ok: false });
+
+  // Missing critical security attributes
+  res.cookie("sid", sessionId, {
+    sameSite: "none"
+  });
+
+  res.json({ ok: true });
+});
+```
+
+## Safe Example
+```js
+app.post("/api/login", async (req, res) => {
+  const user = await verifyCredentials(req.body.email, req.body.password);
+  if (!user) return res.status(401).json({ ok: false });
+
+  const sessionId = await createSession(user.id);
+  res.cookie("sid", sessionId, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/",
+    maxAge: 1000 * 60 * 30 // 30 minutes
+  });
+
+  res.json({ ok: true });
+});
+
+app.post("/api/password/reset/complete", requireAuth, async (req, res) => {
+  await invalidateAllSessions(req.auth.userId);
+  const rotated = await createSession(req.auth.userId);
+
+  res.cookie("sid", rotated, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "strict",
+    path: "/",
+    maxAge: 1000 * 60 * 15
+  });
+
+  res.json({ ok: true });
+});
+```
+
+## Remediation
+1. Set `HttpOnly`, `Secure`, and explicit `SameSite` on all session/auth cookies.
+2. Use HTTPS everywhere; reject insecure origins and mixed-content session transport.
+3. Minimize cookie scope with narrow domain/path and reasonable expiration.
+4. Rotate session IDs on authentication, privilege transitions, and credential recovery.
+5. Invalidate old sessions on logout, password changes, and suspicious activity.
+6. Add CSRF protections compatible with cookie strategy for state-changing requests.
+
+## Verification
+- Inspect `Set-Cookie` headers in browser/network tools for required attributes.
+- Attempt JavaScript cookie reads and confirm auth cookies are inaccessible.
+- Test login over HTTP in non-production environments and ensure secure policy behavior.
+- Validate old session IDs stop working after rotation events.
+- Confirm cross-site POST attempts are blocked by SameSite and CSRF controls.
+
+## False Positives and Exceptions
+- `SameSite=None` can be valid for specific cross-site SSO flows, but requires `Secure` and additional CSRF controls.
+- Development environments on localhost may need adjusted secure handling; document separation from production settings.
+- Stateless bearer tokens in headers are out of scope for this rule but require equivalent protections.
+
+## Related Rules
+- [TG-AUTH-002](./TG-AUTH-002-client-only-authorization.md)
+- [TG-AUTH-005](./TG-AUTH-005-unsafe-password-reset.md)
+- [TG-INPUT-003](./TG-INPUT-003-unsafe-html-or-code-execution.md)

package/skills/torusguard/payload/rules/TG-AUTH-005-unsafe-password-reset.md

@@ -0,0 +1,104 @@
+# TG-AUTH-005: Unsafe Password Reset Flow
+
+## Severity
+High
+
+## Applies To
+- "Forgot password" and account recovery endpoints
+- Email/SMS reset token issuance and verification
+- Self-service credential recovery in web and mobile apps
+- Administrative reset tooling for user accounts
+
+## Why It Matters
+Password reset is a high-value account takeover target because it bypasses existing credentials.
+Weak reset token generation, leakage through URLs/logs, missing expiry, and lack of rate limiting can let attackers hijack accounts at scale.
+Unsafe reset completion logic can also leave existing sessions active, preserving attacker access.
+
+## What TorusGuard Looks For
+- Predictable reset tokens or short numeric codes without brute-force protection.
+- Reset tokens stored in plaintext and compared directly.
+- Missing token expiry, single-use enforcement, or account binding checks.
+- User enumeration through distinct responses for existing vs non-existing emails.
+- Failure to invalidate active sessions after successful password reset.
+
+## Unsafe Example
+```js
+app.post("/api/password/forgot", async (req, res) => {
+  const user = await db.user.findUnique({ where: { email: req.body.email } });
+  if (!user) return res.status(404).json({ ok: false, error: "No account found" });
+
+  const token = Math.floor(Math.random() * 1000000).toString();
+  await db.password_reset.create({
+    data: { user_id: user.id, token, expires_at: null, used: false }
+  });
+
+  await sendMail(user.email, `Reset link: https://app.example/reset?token=${token}`);
+  res.json({ ok: true });
+});
+```
+
+## Safe Example
+```js
+import crypto from "crypto";
+
+app.post("/api/password/forgot", async (req, res) => {
+  const email = String(req.body.email || "").toLowerCase();
+  const user = await db.user.findUnique({ where: { email } });
+
+  // Always return generic response to prevent user enumeration
+  if (user) {
+    const rawToken = crypto.randomBytes(32).toString("hex");
+    const tokenHash = crypto.createHash("sha256").update(rawToken).digest("hex");
+    const expiresAt = new Date(Date.now() + 15 * 60 * 1000);
+
+    await db.password_reset.create({
+      data: { user_id: user.id, token_hash: tokenHash, expires_at: expiresAt, used: false }
+    });
+
+    await sendMail(user.email, `Reset link: https://app.example/reset?token=${rawToken}`);
+  }
+
+  res.json({ ok: true, message: "If an account exists, a reset email has been sent." });
+});
+
+app.post("/api/password/reset", async (req, res) => {
+  const rawToken = String(req.body.token || "");
+  const newPassword = String(req.body.newPassword || "");
+  const tokenHash = crypto.createHash("sha256").update(rawToken).digest("hex");
+
+  const record = await db.password_reset.findFirst({
+    where: { token_hash: tokenHash, used: false, expires_at: { gt: new Date() } }
+  });
+  if (!record) return res.status(400).json({ ok: false, error: "Invalid or expired token" });
+
+  await setUserPassword(record.user_id, newPassword);
+  await db.password_reset.update({ where: { id: record.id }, data: { used: true } });
+  await invalidateAllSessions(record.user_id);
+  res.json({ ok: true });
+});
+```
+
+## Remediation
+1. Generate cryptographically strong, high-entropy reset tokens and store only token hashes.
+2. Enforce short token lifetime, one-time use, and strict account binding.
+3. Apply rate limits and anomaly detection on reset request and token verification endpoints.
+4. Return generic responses for reset initiation to prevent account enumeration.
+5. Invalidate active sessions and recovery artifacts after successful password reset.
+6. Require strong new passwords and optionally step-up verification for risky reset attempts.
+
+## Verification
+- Request reset for known and unknown emails; verify indistinguishable responses.
+- Attempt brute-force token guesses and confirm lockout/rate-limit behavior.
+- Reuse a consumed token and confirm it fails.
+- Use an expired token and verify rejection path.
+- Confirm all existing sessions are invalidated after reset completion.
+
+## False Positives and Exceptions
+- Enterprise SSO environments may delegate password reset externally; local reset flows should be disabled or strongly gated.
+- Short OTP codes can be acceptable when combined with strict attempt limits, device binding, and very short expiry.
+- Manual support resets need controlled operator workflows and audit trails.
+
+## Related Rules
+- [TG-AUTH-001](./TG-AUTH-001-weak-password-storage.md)
+- [TG-AUTH-004](./TG-AUTH-004-insecure-session-cookie.md)
+- [TG-INPUT-001](./TG-INPUT-001-missing-server-validation.md)