secure-coding-rules 2.0.0 → 2.0.1

package/src/templates/frameworks/react-security.md

@@ -0,0 +1,120 @@
+# React Security Rules
+
+> Security rules for React and Next.js frontend applications, covering XSS prevention, state management, and secure component patterns.
+
+## Rules
+
+### 1. Never Use `dangerouslySetInnerHTML` Without Sanitization
+- **DO**: Use DOMPurify or a trusted sanitization library to sanitize HTML before rendering. Prefer rendering structured data with JSX instead of raw HTML.
+- **DON'T**: Pass user-supplied or external data directly to `dangerouslySetInnerHTML`. Never assume HTML content from APIs is safe.
+- **WHY**: `dangerouslySetInnerHTML` bypasses React's built-in XSS protection and injects raw HTML into the DOM. Unsanitized input leads directly to stored or reflected XSS attacks.
+
+### 2. Prevent Memory Leaks and Race Conditions in useEffect
+- **DO**: Return a cleanup function from `useEffect` to cancel async operations (use `AbortController`), clear timers, and unsubscribe from listeners. Use the cleanup flag pattern for async effects.
+- **DON'T**: Fire async requests in `useEffect` without cancellation logic. Ignoring cleanup causes state updates on unmounted components and race conditions.
+- **WHY**: Uncancelled async operations can update state after unmount, causing errors and potentially processing stale or attacker-manipulated responses from superseded requests.
+
+### 3. Never Store Sensitive Data in React State or Context
+- **DO**: Keep tokens in `httpOnly` cookies managed by the server. If client-side storage is unavoidable, use short-lived tokens with secure refresh mechanisms.
+- **DON'T**: Store JWTs, API keys, passwords, or PII in `useState`, `useContext`, Redux, or any client-side state. Never put secrets in `localStorage` or `sessionStorage`.
+- **WHY**: Client-side state is fully accessible via browser DevTools, XSS attacks, and browser extensions. Any data in React state should be considered public to the client.
+
+### 4. Never Pass Sensitive Data Through Props
+- **DO**: Fetch sensitive data only where it is needed. Use server-side rendering or secure API calls within the consuming component itself.
+- **DON'T**: Pass tokens, secrets, or full user records through component props chains. Props are visible in React DevTools and can leak through component trees.
+- **WHY**: Prop drilling exposes sensitive data across the component tree. React DevTools displays all props in plaintext, and any parent component re-render can unintentionally log or expose prop values.
+
+### 5. Guard Server Components Against Data Leakage
+- **DO**: Separate server-only logic into files with `"server-only"` import guard. Verify that server component data is filtered before passing to client components.
+- **DON'T**: Import server-side utilities or secrets into client components. Never pass database records or internal IDs directly from server to client components without filtering.
+- **WHY**: Next.js server components run on the server but their return values are serialized and sent to the client. Sensitive data in server component output ends up in the client-side HTML or RSC payload.
+
+### 6. Use Error Boundaries with React.lazy Code Splitting
+- **DO**: Wrap `React.lazy` components with `<Suspense>` and an `<ErrorBoundary>`. Log errors securely without exposing internal paths or stack traces to users.
+- **DON'T**: Let lazy-loaded component failures crash the entire app or display raw error messages to users.
+- **WHY**: Failed chunk loads (network errors, deploy mismatches) can crash the app. Without error boundaries, users see raw error details that may reveal internal architecture, file paths, or API endpoints.
+
+### 7. Sanitize URL Schemes in Dynamic Links and Redirects
+- **DO**: Validate that dynamic `href` values use `https:` or safe schemes. Use an allowlist for URL schemes. Encode URL parameters with `encodeURIComponent`.
+- **DON'T**: Render user-supplied URLs in `<a href>` or `window.location` without validation. Never allow `javascript:`, `data:`, or `vbscript:` schemes.
+- **WHY**: React does not sanitize `href` attributes. A `javascript:` URI in an anchor tag executes arbitrary code when clicked, leading to XSS.
+
+## Code Examples
+
+### Bad Practice
+```jsx
+// XSS via dangerouslySetInnerHTML
+function Comment({ body }) {
+  return <div dangerouslySetInnerHTML={{ __html: body }} />;
+}
+
+// Race condition — no cleanup in useEffect
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    fetch(`/api/users/${userId}`)
+      .then((res) => res.json())
+      .then((data) => setUser(data)); // Runs even if unmounted
+  }, [userId]);
+}
+
+// Token stored in React state
+function App() {
+  const [token, setToken] = useState(localStorage.getItem("jwt"));
+  return <AppContext.Provider value={{ token }}>{/* ... */}</AppContext.Provider>;
+}
+```
+
+### Good Practice
+```jsx
+import DOMPurify from "dompurify";
+
+// Sanitized HTML rendering
+function Comment({ body }) {
+  const clean = DOMPurify.sanitize(body);
+  return <div dangerouslySetInnerHTML={{ __html: clean }} />;
+}
+
+// Proper cleanup with AbortController
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    fetch(`/api/users/${userId}`, { signal: controller.signal })
+      .then((res) => res.json())
+      .then((data) => setUser(data))
+      .catch((err) => {
+        if (err.name !== "AbortError") console.error(err);
+      });
+    return () => controller.abort();
+  }, [userId]);
+}
+
+// Error boundary with lazy loading
+const LazyDashboard = React.lazy(() => import("./Dashboard"));
+
+function App() {
+  return (
+    <ErrorBoundary fallback={<p>Something went wrong.</p>}>
+      <Suspense fallback={<p>Loading...</p>}>
+        <LazyDashboard />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+// Safe URL validation
+function SafeLink({ href, children }) {
+  const isSafe = /^https?:\/\//i.test(href);
+  return isSafe ? <a href={href}>{children}</a> : <span>{children}</span>;
+}
+```
+
+## Quick Checklist
+- [ ] No `dangerouslySetInnerHTML` without DOMPurify sanitization
+- [ ] All `useEffect` async operations have cleanup / `AbortController`
+- [ ] No tokens, passwords, or API keys stored in React state
+- [ ] Sensitive data is not passed through props across component boundaries
+- [ ] Server components use `"server-only"` guard and filter data before client handoff
+- [ ] `React.lazy` components are wrapped with `ErrorBoundary` and `Suspense`
+- [ ] Dynamic URLs are validated against an allowlist of safe schemes

package/src/templates/typescript/typescript-security.md

@@ -0,0 +1,113 @@
+# TypeScript Security Rules
+
+> TypeScript-specific security rules for leveraging the type system to prevent vulnerabilities at compile time and enforce runtime safety boundaries.
+
+## Rules
+
+### 1. Enable Strict Mode and strictNullChecks
+- **DO**: Set `"strict": true` and `"strictNullChecks": true` in `tsconfig.json`. Treat compiler warnings as errors in CI.
+- **DON'T**: Disable strict checks to "fix" type errors quickly. Loosening strictness hides real bugs.
+- **WHY**: Strict mode catches null/undefined dereferences, implicit `any` usage, and other unsafe patterns at compile time before they become runtime vulnerabilities.
+
+### 2. Never Use `as any` or Excessive Type Assertions
+- **DO**: Fix type errors by correcting the underlying types. Use type narrowing (`instanceof`, `in`, discriminated unions) to safely refine types.
+- **DON'T**: Use `as any`, `as unknown as T`, or `@ts-ignore` to silence type errors. Each assertion is an unverified trust boundary.
+- **WHY**: Type assertions bypass the compiler's safety checks. `as any` effectively disables TypeScript's protection, allowing injection, null dereference, and data integrity bugs to slip through.
+
+### 3. Use `unknown` Instead of `any` for External Data
+- **DO**: Type all external inputs (API responses, user input, file reads, environment variables) as `unknown` and narrow with validation before use.
+- **DON'T**: Type external data as `any` or trust its shape without validation. Never pass unvalidated external data directly to business logic.
+- **WHY**: External data is the primary attack surface. `unknown` forces explicit validation, preventing injection, prototype pollution, and type confusion attacks.
+
+### 4. Validate External Data at Runtime with Schema Libraries
+- **DO**: Use Zod, io-ts, or similar libraries to define schemas and validate all data crossing trust boundaries (API inputs, webhook payloads, config files).
+- **DON'T**: Rely solely on TypeScript interfaces for external data — interfaces are erased at compile time and provide zero runtime protection.
+- **WHY**: TypeScript's type system exists only at compile time. Attackers send raw HTTP requests; runtime validation is the only real defense against malformed or malicious payloads.
+
+### 5. Use Generics for Type-Safe API Response Handling
+- **DO**: Define generic API client functions that return validated, typed responses. Pair generics with runtime schema validation.
+- **DON'T**: Cast API responses with `as T` without validation. A generic function that skips validation gives false confidence.
+- **WHY**: Generic + validation patterns ensure that API response handling is both type-safe and runtime-safe, preventing type confusion from unexpected server responses.
+
+### 6. Prefer `as const` Assertions Over Enums
+- **DO**: Use `as const` objects or union types for fixed value sets. This provides better type narrowing and tree-shaking.
+- **DON'T**: Use numeric enums, which can be accessed with arbitrary numbers at runtime (`MyEnum[999]` returns `undefined` without error).
+- **WHY**: Numeric enums allow reverse mapping that accepts any number, bypassing intended value restrictions. `as const` objects are immutable and provide exact literal types.
+
+### 7. Audit `declare module` and Ambient Type Declarations
+- **DO**: Keep ambient declarations (`declare module`, `declare global`, `.d.ts` files) minimal and review them carefully. Ensure they accurately reflect the runtime API.
+- **DON'T**: Use `declare module` to paper over missing types with permissive definitions (e.g., `declare module '*' { const x: any; export default x; }`).
+- **WHY**: Ambient declarations override the compiler's type checking. Incorrect declarations create a false sense of safety — the compiler trusts them unconditionally, so inaccurate declarations hide real vulnerabilities.
+
+## Code Examples
+
+### Bad Practice
+```typescript
+// Using 'any' for API response — no safety at all
+async function getUser(id: string): Promise<any> {
+  const res = await fetch(`/api/users/${id}`);
+  return res.json(); // any — caller has no type safety
+}
+
+// Type assertion without validation
+interface Config {
+  apiKey: string;
+  dbUrl: string;
+}
+const config = JSON.parse(rawInput) as Config; // Blindly trusted
+
+// Numeric enum allows arbitrary values
+enum Status {
+  Active = 0,
+  Inactive = 1,
+}
+const s: Status = 999; // No compile error!
+```
+
+### Good Practice
+```typescript
+import { z } from "zod";
+
+// Runtime schema validation with Zod
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  role: z.enum(["admin", "user", "viewer"]),
+});
+type User = z.infer<typeof UserSchema>;
+
+// Type-safe API client with runtime validation
+async function fetchApi<T>(url: string, schema: z.ZodType<T>): Promise<T> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const data: unknown = await res.json();
+  return schema.parse(data); // Throws if invalid
+}
+
+const user = await fetchApi("/api/users/123", UserSchema);
+
+// as const instead of enum
+const STATUS = {
+  Active: "active",
+  Inactive: "inactive",
+} as const;
+type Status = (typeof STATUS)[keyof typeof STATUS]; // "active" | "inactive"
+
+// unknown + narrowing for external data
+function processInput(input: unknown): string {
+  if (typeof input !== "string") {
+    throw new Error("Expected string input");
+  }
+  return input.trim(); // Now safely narrowed to string
+}
+```
+
+## Quick Checklist
+- [ ] `tsconfig.json` has `"strict": true` enabled
+- [ ] No `as any` or `@ts-ignore` in production code
+- [ ] All external data is typed as `unknown` and validated at runtime
+- [ ] Zod or equivalent schema validation is used at trust boundaries
+- [ ] Generic API functions include runtime validation, not just type assertions
+- [ ] `as const` is used instead of numeric enums for fixed value sets
+- [ ] Ambient type declarations are reviewed and accurately reflect runtime behavior