@pnx-mixtape/mxds 0.1.0-rc.3 → 0.1.0-rc.5

package/docs/Security.md

@@ -0,0 +1,444 @@
+# Security Guidelines
+
+Security best practices for the Mixtape Design System.
+
+## Table of Contents
+
+- [XSS Prevention](#xss-prevention)
+- [Input Validation](#input-validation)
+- [URL Safety](#url-safety)
+- [Data Sanitization](#data-sanitization)
+- [Secure Dependencies](#secure-dependencies)
+- [Information Disclosure](#information-disclosure)
+
+---
+
+## XSS Prevention
+
+### Never Use dangerouslySetInnerHTML
+
+```tsx
+// ❌ BAD - XSS vulnerability
+<div dangerouslySetInnerHTML={{ __html: userContent }} />
+
+// User provides: <img src=x onerror='alert(document.cookie)'>
+// Result: JavaScript executes!
+
+// ✅ GOOD - Safe rendering
+<div>{userContent}</div>
+
+// React automatically escapes content
+// Result: Displays as text, doesn't execute
+```
+
+### Never Use innerHTML
+
+```typescript
+// ❌ BAD - XSS vulnerability
+element.innerHTML = htmlString
+
+// ✅ GOOD - Use DOMParser
+const parser = new DOMParser()
+const doc = parser.parseFromString(htmlString, "text/html")
+const safeElement = doc.body.firstElementChild
+
+// Or use the createElement utility
+import { createElement } from "../Utility/utilities"
+const safeElement = createElement(htmlString)
+```
+
+### The createElement Utility
+
+```typescript
+// Safe HTML parsing without script execution
+export const createElement = (string: string): Element | null => {
+  try {
+    const parser = new DOMParser()
+    const doc = parser.parseFromString(string, "text/html")
+    return doc.body.firstElementChild
+  } catch (error) {
+    if (process.env.NODE_ENV !== "production") console.error(error)
+    return null
+  }
+}
+
+// Usage
+const element = createElement('<div class="safe">Content</div>')
+// Scripts in the string won't execute
+```
+
+---
+
+## Input Validation
+
+### Use the validators Utility
+
+Always validate user input before using it:
+
+```typescript
+import { validators } from "../Utility/utilities"
+
+// ✅ GOOD - Validate everything
+function handlePageChange(pageParam: string) {
+  // Validate page is an integer within bounds
+  if (!validators.integer(pageParam, 1, lastPage)) {
+    console.warn("Invalid page parameter")
+    return 1 // Safe fallback
+  }
+
+  return parseInt(pageParam, 10)
+}
+```
+
+### Validate Numbers
+
+```typescript
+import { validators } from "../Utility/utilities"
+
+// ❌ BAD - No validation
+const page = parseInt(userInput) // Could be NaN, Infinity, etc.
+
+// ✅ GOOD - Validate first
+if (!validators.integer(userInput, 1, 100)) {
+  throw new Error("Page must be between 1 and 100")
+}
+const page = parseInt(userInput, 10)
+```
+
+### Validate JSON
+
+```typescript
+import { validators } from "../Utility/utilities"
+
+// ❌ BAD - Uncaught parse error
+const data = JSON.parse(localStorage.getItem("data"))
+
+// ✅ GOOD - Validate before parsing
+const stored = localStorage.getItem("data")
+if (!validators.json(stored)) {
+  return defaultValue // Safe fallback
+}
+
+try {
+  const data = JSON.parse(stored)
+  return data
+} catch {
+  return defaultValue
+}
+```
+
+---
+
+## URL Safety
+
+### Validate All URLs
+
+```typescript
+import { validators } from "../Utility/utilities"
+
+// ❌ BAD - Accepts any URL including javascript:
+window.open(userProvidedUrl)
+
+// ✅ GOOD - Validate protocol
+if (!validators.url(userProvidedUrl)) {
+  console.error("Invalid URL")
+  userProvidedUrl = window.location.href // Safe fallback
+}
+window.open(userProvidedUrl)
+```
+
+### The validators.url Function
+
+```typescript
+// Only allows http: and https: by default
+validators.url("https://example.com") // true
+validators.url("http://example.com") // true
+validators.url("javascript:alert(1)") // false
+validators.url("data:text/html,...") // false
+validators.url("file:///etc/passwd") // false
+
+// Custom protocols if needed
+validators.url("ftp://example.com", ["ftp:", "ftps:"]) // true
+```
+
+### External Links
+
+Always add `rel="noopener noreferrer"` to external links with `target="_blank"`:
+
+```tsx
+// ❌ BAD - Vulnerable to tabnapping
+<a href="https://external.com" target="_blank">
+  Link
+</a>
+
+// ✅ GOOD - Secure
+<a href="https://external.com" target="_blank" rel="noopener noreferrer">
+  Link
+</a>
+```
+
+**Why?** Without `noopener`, the opened page can access `window.opener` and redirect your page to a phishing site.
+
+---
+
+## Data Sanitization
+
+### localStorage Security
+
+```typescript
+// ⚠️ WARNING: localStorage is NOT secure
+// - Data is stored UNENCRYPTED
+// - Accessible to all scripts on same origin
+// - Persists across sessions
+
+// ❌ BAD - Sensitive data
+localStorage.setItem("authToken", token)
+localStorage.setItem("password", password)
+localStorage.setItem("creditCard", cc)
+
+// ✅ GOOD - Non-sensitive data only
+localStorage.setItem("theme", "dark")
+localStorage.setItem("language", "en")
+localStorage.setItem("preferences", JSON.stringify(prefs))
+
+// For sensitive data, use:
+// - httpOnly cookies (server-side only)
+// - sessionStorage (cleared on close)
+// - Memory-only (JavaScript variables)
+```
+
+### Cookie Security
+
+```typescript
+import Cookies from "js-cookie"
+
+// ✅ GOOD - Secure cookie settings
+Cookies.set("session", value, {
+  path: "/",
+  expires: 7,
+  sameSite: "Lax", // CSRF protection
+  secure: true, // HTTPS only (production)
+  httpOnly: false, // Client-side access needed
+})
+
+// For authentication tokens:
+// - Use httpOnly: true (JavaScript can't access)
+// - Set by server, not client-side
+```
+
+---
+
+## Secure Dependencies
+
+### Regular Audits
+
+```bash
+# Run security audit
+pnpm audit
+
+# Fix vulnerabilities
+pnpm audit --fix
+
+# Check for outdated packages
+pnpm outdated
+```
+
+### Monitor CVEs
+
+The design system uses:
+
+- **Oxlint** instead of ESLint (faster, safer)
+- **DOMParser** instead of innerHTML (safer)
+- **Validators utility** instead of heavy validation libs (smaller attack surface)
+- **AbortController** for cleanup (browser standard, no deps)
+
+### Keep Dependencies Updated
+
+```bash
+# Update dependencies
+pnpm update
+
+# Update to latest versions
+pnpm update --latest
+
+# Check for security advisories
+pnpm audit
+```
+
+---
+
+## Information Disclosure
+
+### Environment-Specific Logging
+
+```typescript
+// ❌ BAD - Logs sensitive info in production
+console.error("Failed to authenticate:", email, password)
+console.log("Database query:", query)
+console.warn("API key:", apiKey)
+
+// ✅ GOOD - Only log in development
+if (process.env.NODE_ENV !== "production") {
+  console.error("Failed to authenticate:", email)
+  // Don't log password ever!
+}
+
+// For user-facing errors (OK in production)
+console.error("Could not copy URL to clipboard") // Generic message
+console.error("Invalid email address") // No sensitive data
+```
+
+### Error Messages
+
+```typescript
+// ❌ BAD - Reveals internal structure
+throw new Error(`User ${userId} not found in database table users_auth`)
+
+// ✅ GOOD - Generic public message
+throw new Error("User not found")
+
+// Log details only in development
+if (process.env.NODE_ENV !== "production") {
+  console.error("Database error:", details)
+}
+```
+
+---
+
+## Security Checklist
+
+Before shipping, verify:
+
+- [ ] No `dangerouslySetInnerHTML` usage
+- [ ] No `innerHTML` usage
+- [ ] All URLs validated with `validators.url()`
+- [ ] All numbers validated with `validators.integer()` or `validators.number()`
+- [ ] All JSON validated with `validators.json()` before parsing
+- [ ] External links have `rel="noopener noreferrer"`
+- [ ] No sensitive data in localStorage
+- [ ] Environment-specific logging (NODE_ENV checks)
+- [ ] Generic error messages (no internal details)
+- [ ] Dependencies audited (`pnpm audit`)
+- [ ] No hardcoded credentials
+- [ ] HTTPS used in production
+- [ ] CSRF protection (SameSite cookies)
+- [ ] Input sanitization on all user data
+- [ ] XSS testing done (try `<script>alert(1)</script>`)
+
+---
+
+## Testing for Vulnerabilities
+
+### XSS Testing
+
+```javascript
+// Test 1: Try to inject script in all inputs
+const xssPayloads = [
+  "<script>alert(1)</script>",
+  "<img src=x onerror=alert(1)>",
+  "javascript:alert(1)",
+  "<svg onload=alert(1)>",
+  '"><script>alert(1)</script>',
+]
+
+xssPayloads.forEach(payload => {
+  // Try in every input field
+  // Expected: Should be escaped/rejected
+})
+```
+
+### URL Injection Testing
+
+```javascript
+// Test 2: Try malicious URLs
+const maliciousUrls = [
+  "javascript:alert(document.cookie)",
+  "data:text/html,<script>alert(1)</script>",
+  "file:///etc/passwd",
+  "vbscript:msgbox(1)",
+]
+
+maliciousUrls.forEach(url => {
+  validators.url(url) // Should return false
+})
+```
+
+### Input Validation Testing
+
+```javascript
+// Test 3: Try to break validation
+validators.integer("999999999999999", 1, 10) // Should reject
+validators.integer("-1", 1, 10) // Should reject
+validators.integer("5.5", 1, 10) // Should reject (not integer)
+validators.integer("abc", 1, 10) // Should reject
+```
+
+---
+
+## OWASP Top 10 Coverage
+
+### A03:2021 – Injection
+
+- ✅ No innerHTML usage (XSS prevention)
+- ✅ No dangerouslySetInnerHTML (XSS prevention)
+- ✅ DOMParser for safe HTML parsing
+- ✅ Input validation with validators utility
+
+### A04:2021 – Insecure Design
+
+- ✅ URL protocol validation
+- ✅ Bounds checking on all numbers
+- ✅ Secure-by-default patterns
+
+### A05:2021 – Security Misconfiguration
+
+- ✅ Environment-specific logging
+- ✅ Generic error messages
+- ✅ Secure cookie defaults (SameSite, Secure)
+
+### A06:2021 – Vulnerable Components
+
+- ✅ Regular `pnpm audit` runs
+- ✅ Dependencies kept updated
+- ✅ Minimal dependencies (smaller attack surface)
+
+### A07:2021 – Identification and Authentication
+
+- ✅ No credentials in localStorage
+- ✅ Secure cookie practices
+- ✅ httpOnly recommended for auth tokens
+
+### A08:2021 – Software and Data Integrity
+
+- ✅ JSON validation before parsing
+- ✅ Try-catch around all parsing
+- ✅ Graceful fallbacks on bad data
+
+### A09:2021 – Logging Failures
+
+- ✅ Environment-specific logging
+- ✅ No sensitive data in logs
+- ✅ User-facing errors are generic
+
+### A10:2021 – Server-Side Request Forgery
+
+- ✅ URL validation before requests
+- ✅ Protocol whitelisting
+- ✅ Same-origin checks where applicable
+
+---
+
+## Resources
+
+- [OWASP Top 10](https://owasp.org/Top10/)
+- [OWASP Cheat Sheets](https://cheatsheetseries.owasp.org/)
+- [MDN Security](https://developer.mozilla.org/en-US/docs/Web/Security)
+- [Web.dev Security](https://web.dev/secure/)
+
+---
+
+## Related Documentation
+
+- [Code Quality Guidelines](./CodeQuality.md)
+- [Input Validation (API.md)](./API.md#validators)
+- [Memory Management](./MemoryManagement.md)