ship-safe 1.0.1 → 3.0.0

package/README.md

@@ -1,6 +1,17 @@
-# Ship Safe
+<p align="center">
+  <img src=".github/assets/logo%20ship%20safe.png" alt="Ship Safe Logo" width="180" />
+</p>
 
-**Don't let vibe coding leak your API keys.**
+<h1 align="center">Ship Safe</h1>
+
+<p align="center"><strong>Don't let vibe coding leak your API keys.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ship-safe"><img src="https://badge.fury.io/js/ship-safe.svg" alt="npm version" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+---
 
 You're shipping fast. You're using AI to write code. You're one `git push` away from exposing your database credentials to the world.
 
@@ -11,9 +22,15 @@ You're shipping fast. You're using AI to write code. You're one `git push` away
 ## Quick Start
 
 ```bash
-# Scan your project for leaked secrets (no install required!)
+# Scan for leaked secrets (no install required!)
 npx ship-safe scan .
 
+# Auto-generate .env.example from found secrets
+npx ship-safe fix
+
+# Block git push if secrets are found
+npx ship-safe guard
+
 # Run the launch-day security checklist
 npx ship-safe checklist
 
@@ -21,7 +38,21 @@ npx ship-safe checklist
 npx ship-safe init
 ```
 
-That's it. Three commands to secure your MVP.
+That's it. Five commands to secure your MVP.
+
+![ship-safe terminal demo](.github/assets/ship%20safe%20terminal.jpg)
+
+### Let AI Do It For You
+
+Copy this prompt to your AI coding assistant:
+
+```
+Run "npx ship-safe scan ." on my project and fix any secrets you find.
+Then run "npx ship-safe init" to add security configs.
+Explain what you're doing as you go.
+```
+
+[More AI prompts for specific frameworks](./AI_SECURITY_PROMPT.md)
 
 ---
 
@@ -59,7 +90,40 @@ npx ship-safe scan . -v
 
 **Exit codes:** Returns `1` if secrets found (useful for CI), `0` if clean.
 
-**Detects:** OpenAI keys, AWS credentials, GitHub tokens, Stripe keys, Supabase service keys, database URLs, private keys, and 20+ more patterns.
+**Flags:**
+- `--json` — structured JSON output for CI pipelines
+- `--sarif` — SARIF format for GitHub Code Scanning
+- `--include-tests` — also scan test/spec/fixture files (excluded by default)
+- `-v` — verbose mode
+
+**Suppress false positives:**
+```bash
+const apiKey = 'example-key'; // ship-safe-ignore
+```
+Or exclude paths with `.ship-safeignore` (gitignore syntax).
+
+**Custom patterns** — create `.ship-safe.json` in your project root:
+```json
+{
+  "patterns": [
+    {
+      "name": "My Internal API Key",
+      "pattern": "MYAPP_[A-Z0-9]{32}",
+      "severity": "high",
+      "description": "Internal key for myapp services."
+    }
+  ]
+}
+```
+
+**Detects 50+ secret patterns:**
+- **AI/ML:** OpenAI, Anthropic, Google AI, Cohere, Replicate, Hugging Face
+- **Auth:** Clerk, Auth0, Supabase Auth
+- **Cloud:** AWS, Google Cloud, Azure
+- **Database:** Supabase, PlanetScale, Neon, MongoDB, PostgreSQL, MySQL
+- **Payment:** Stripe, PayPal
+- **Messaging:** Twilio, SendGrid, Resend
+- **And more:** GitHub tokens, private keys, JWTs, generic secrets
 
 ---
 
@@ -103,6 +167,66 @@ npx ship-safe init -f
 
 ---
 
+### `npx ship-safe fix`
+
+Scan for secrets and auto-generate a `.env.example` file.
+
+```bash
+# Scan and generate .env.example
+npx ship-safe fix
+
+# Preview what would be generated without writing it
+npx ship-safe fix --dry-run
+```
+
+---
+
+### `npx ship-safe guard`
+
+Install a git hook that blocks pushes if secrets are found. Works with or without Husky.
+
+```bash
+# Install pre-push hook (runs scan before every git push)
+npx ship-safe guard
+
+# Install pre-commit hook instead
+npx ship-safe guard --pre-commit
+
+# Remove installed hooks
+npx ship-safe guard remove
+```
+
+**Suppress false positives:**
+- Add `# ship-safe-ignore` as a comment on a line to skip it
+- Create `.ship-safeignore` (gitignore syntax) to exclude paths
+
+---
+
+### `npx ship-safe mcp`
+
+Start ship-safe as an MCP server so AI editors can call it directly.
+
+**Setup (Claude Desktop)** — add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "ship-safe": {
+      "command": "npx",
+      "args": ["ship-safe", "mcp"]
+    }
+  }
+}
+```
+
+Works with Claude Desktop, Cursor, Windsurf, Zed, and any MCP-compatible editor.
+
+**Available tools:**
+- `scan_secrets` — scan a directory for leaked secrets
+- `get_checklist` — return the security checklist as structured data
+- `analyze_file` — analyze a single file for issues
+
+---
+
 ## What's Inside
 
 ### [`/checklists`](./checklists)
@@ -111,19 +235,149 @@ npx ship-safe init -f
 
 ### [`/configs`](./configs)
 **Secure defaults for popular stacks. Drop-in ready.**
-- [Next.js Security Headers](./configs/nextjs-security-headers.js) - CSP, X-Frame-Options, and more
 
-### [`/scripts`](./scripts)
-**Automated scanning tools. Run them in CI or locally.**
-- [Secret Scanner](./scripts/scan_secrets.py) - Python version of the secret scanner
+| Stack | Files |
+|-------|-------|
+| **Next.js** | [Security Headers](./configs/nextjs-security-headers.js) - CSP, X-Frame-Options, HSTS |
+| **Supabase** | [RLS Templates](./configs/supabase/rls-templates.sql) \| [Security Checklist](./configs/supabase/security-checklist.md) \| [Secure Client](./configs/supabase/secure-client.ts) |
+| **Firebase** | [Firestore Rules](./configs/firebase/firestore-rules.txt) \| [Storage Rules](./configs/firebase/storage-rules.txt) \| [Security Checklist](./configs/firebase/security-checklist.md) |
 
 ### [`/snippets`](./snippets)
 **Copy-paste code blocks for common security patterns.**
-- Rate limiting, auth middleware, input validation (coming soon)
+
+| Category | Files |
+|----------|-------|
+| **Rate Limiting** | [Upstash Redis](./snippets/rate-limiting/upstash-ratelimit.ts) \| [Next.js Middleware](./snippets/rate-limiting/nextjs-middleware.ts) |
+| **Authentication** | [JWT Security Checklist](./snippets/auth/jwt-checklist.md) |
+| **API Security** | [CORS Config](./snippets/api-security/cors-config.ts) \| [Input Validation](./snippets/api-security/input-validation.ts) \| [API Checklist](./snippets/api-security/api-security-checklist.md) |
 
 ### [`/ai-defense`](./ai-defense)
-**Protect your AI features from abuse.**
-- [System Prompt Armor](./ai-defense/system-prompt-armor.md) - Prevent prompt injection attacks
+**Protect your AI features from abuse and cost explosions.**
+
+| File | Description |
+|------|-------------|
+| [LLM Security Checklist](./ai-defense/llm-security-checklist.md) | Based on OWASP LLM Top 10 - prompt injection, data protection, scope control |
+| [Prompt Injection Patterns](./ai-defense/prompt-injection-patterns.js) | Regex patterns to detect 25+ injection attempts |
+| [Cost Protection Guide](./ai-defense/cost-protection.md) | Prevent $50k surprise bills - rate limits, budget caps, circuit breakers |
+| [System Prompt Armor](./ai-defense/system-prompt-armor.md) | Template for hardened system prompts |
+
+### [`/scripts`](./scripts)
+**Automated scanning tools. Run them in CI or locally.**
+- [Secret Scanner](./scripts/scan_secrets.py) - Python version of the secret scanner
+
+---
+
+## AI/LLM Security
+
+Building with AI? Don't let it bankrupt you or get hijacked.
+
+### Quick Setup
+
+```typescript
+import { containsInjectionAttempt } from './ai-defense/prompt-injection-patterns';
+
+async function handleChat(userInput: string) {
+  // 1. Check for injection attempts
+  const { detected } = containsInjectionAttempt(userInput);
+  if (detected) {
+    return "I can't process that request.";
+  }
+
+  // 2. Rate limit per user
+  const { success } = await ratelimit.limit(userId);
+  if (!success) {
+    return "Too many requests. Please slow down.";
+  }
+
+  // 3. Check budget before calling
+  await checkUserBudget(userId, estimatedCost);
+
+  // 4. Make the API call with token limits
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages,
+    max_tokens: 500, // Hard cap
+  });
+
+  return response;
+}
+```
+
+### Cost Protection Layers
+
+1. **Token limits** - Cap input/output per request
+2. **Rate limits** - Cap requests per user (10/min)
+3. **Budget caps** - Daily ($1) and monthly ($10) per user
+4. **Circuit breaker** - Disable AI when global budget hit
+5. **Provider limits** - Set hard limits in OpenAI/Anthropic dashboard
+
+[Full cost protection guide →](./ai-defense/cost-protection.md)
+
+---
+
+## Database Security
+
+### Supabase RLS Templates
+
+```sql
+-- Users can only see their own data
+CREATE POLICY "Users own their data" ON items
+  FOR ALL USING (auth.uid() = user_id);
+
+-- Read-only public data
+CREATE POLICY "Public read access" ON public_items
+  FOR SELECT USING (true);
+```
+
+[6 more RLS patterns →](./configs/supabase/rls-templates.sql)
+
+### Firebase Security Rules
+
+```javascript
+// Users can only access their own documents
+match /users/{userId} {
+  allow read, write: if request.auth != null
+    && request.auth.uid == userId;
+}
+```
+
+[Full Firestore rules template →](./configs/firebase/firestore-rules.txt)
+
+---
+
+## API Security
+
+### CORS (Don't use `*` in production)
+
+```typescript
+const ALLOWED_ORIGINS = [
+  'https://yourapp.com',
+  'https://www.yourapp.com',
+];
+
+// Only allow specific origins
+if (origin && ALLOWED_ORIGINS.includes(origin)) {
+  headers['Access-Control-Allow-Origin'] = origin;
+}
+```
+
+[CORS configs for Next.js, Express, Fastify, Hono →](./snippets/api-security/cors-config.ts)
+
+### Input Validation (Zod)
+
+```typescript
+const createUserSchema = z.object({
+  email: z.string().email().max(255),
+  password: z.string().min(8).max(128),
+});
+
+const result = createUserSchema.safeParse(body);
+if (!result.success) {
+  return Response.json({ error: result.error.issues }, { status: 400 });
+}
+```
+
+[Full validation patterns →](./snippets/api-security/input-validation.ts)
 
 ---
 
@@ -152,11 +406,13 @@ The scan exits with code `1` if secrets are found, failing your build.
 
 ## The 5-Minute Security Checklist
 
-1. Run `npx ship-safe scan .` on your project
-2. Run `npx ship-safe init` to add security configs
-3. Add security headers to your Next.js config
-4. Run `npx ship-safe checklist` before launching
-5. If using AI features, add the [System Prompt Armor](./ai-defense/system-prompt-armor.md)
+1. ✅ Run `npx ship-safe scan .` on your project
+2. ✅ Run `npx ship-safe init` to add security configs
+3. ✅ Add security headers to your Next.js config
+4. ✅ Run `npx ship-safe checklist` before launching
+5. ✅ If using AI features, implement [cost protection](./ai-defense/cost-protection.md)
+6. ✅ If using Supabase, check the [RLS checklist](./configs/supabase/security-checklist.md)
+7. ✅ If using Firebase, check the [Firebase checklist](./configs/firebase/security-checklist.md)
 
 ---
 
@@ -178,15 +434,17 @@ Found a security pattern that saved your app? Share it!
 3. Include educational comments explaining *why* it matters
 4. Open a PR
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
 ---
 
-## Stack-Specific Guides (Coming Soon)
+## Security Standards Reference
 
-- [ ] Supabase Security Defaults
-- [ ] Firebase Rules Templates
-- [ ] Vercel Environment Variables
-- [ ] Stripe Webhook Validation
-- [ ] Clerk/Auth.js Hardening
+This toolkit is based on:
+- [OWASP Top 10 Web 2025](https://owasp.org/Top10/)
+- [OWASP Top 10 Mobile 2024](https://owasp.org/www-project-mobile-top-10/)
+- [OWASP LLM Top 10 2025](https://genai.owasp.org/llm-top-10/)
+- [OWASP API Security Top 10 2023](https://owasp.org/API-Security/)
 
 ---
 

package/ai-defense/cost-protection.md

@@ -0,0 +1,292 @@
+# AI Cost Protection Guide
+
+**Prevent your AI features from bankrupting you.**
+
+Real incidents: $50k+ bills from runaway AI usage, abuse, or misconfiguration.
+
+---
+
+## Why Cost Protection Matters
+
+| Scenario | Risk |
+|----------|------|
+| Leaked API key | Anyone can rack up charges on your account |
+| No rate limits | Single user sends 10,000 requests |
+| Long responses | GPT-4 response = $0.03-0.12 per request |
+| Infinite loops | Code bug calls AI repeatedly |
+| Viral launch | 10x traffic = 10x costs |
+
+---
+
+## Layer 1: API Key Security
+
+### Keep keys server-side only
+
+```typescript
+// BAD: Key in frontend code
+const openai = new OpenAI({ apiKey: 'sk-...' });
+
+// GOOD: Key in server environment variable
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+```
+
+### Scan for leaked keys
+
+```bash
+npx ship-safe scan .
+```
+
+### Rotate keys periodically
+
+- OpenAI: Dashboard > API Keys > Create new > Delete old
+- Anthropic: Console > API Keys > Rotate
+
+---
+
+## Layer 2: Request Limits
+
+### Token limits per request
+
+```typescript
+// Limit input
+const MAX_INPUT_CHARS = 2000;
+if (userInput.length > MAX_INPUT_CHARS) {
+  return "Message too long";
+}
+
+// Limit output
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: messages,
+  max_tokens: 500,  // Hard cap on response length
+});
+```
+
+### Rate limiting per user
+
+```typescript
+import { Ratelimit } from '@upstash/ratelimit';
+
+const aiRatelimit = new Ratelimit({
+  redis,
+  limiter: Ratelimit.slidingWindow(10, '1 m'),  // 10 requests/minute
+});
+
+async function aiHandler(request, userId) {
+  const { success } = await aiRatelimit.limit(userId);
+  if (!success) {
+    return new Response('Too many requests', { status: 429 });
+  }
+  // Process request
+}
+```
+
+### Global rate limiting
+
+```typescript
+const globalRatelimit = new Ratelimit({
+  redis,
+  limiter: Ratelimit.slidingWindow(1000, '1 h'),  // 1000 requests/hour total
+  prefix: 'ratelimit:global:ai',
+});
+```
+
+---
+
+## Layer 3: Budget Caps
+
+### Track usage in database
+
+```typescript
+interface AIUsageRecord {
+  userId: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cost: number;
+  timestamp: Date;
+}
+
+async function logUsage(usage: AIUsageRecord) {
+  await db.aiUsage.create({ data: usage });
+}
+```
+
+### Calculate cost before request
+
+```typescript
+// Approximate cost calculation
+const COSTS = {
+  'gpt-4': { input: 0.03 / 1000, output: 0.06 / 1000 },
+  'gpt-4-turbo': { input: 0.01 / 1000, output: 0.03 / 1000 },
+  'gpt-3.5-turbo': { input: 0.0005 / 1000, output: 0.0015 / 1000 },
+  'claude-3-opus': { input: 0.015 / 1000, output: 0.075 / 1000 },
+  'claude-3-sonnet': { input: 0.003 / 1000, output: 0.015 / 1000 },
+};
+
+function estimateCost(model: string, inputTokens: number, maxOutputTokens: number) {
+  const rates = COSTS[model] || COSTS['gpt-4'];
+  return (inputTokens * rates.input) + (maxOutputTokens * rates.output);
+}
+```
+
+### Enforce user budget
+
+```typescript
+async function checkUserBudget(userId: string, estimatedCost: number) {
+  const dailyLimit = 1.00;  // $1/day per user
+  const monthlyLimit = 10.00;  // $10/month per user
+
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+
+  const dailyUsage = await db.aiUsage.aggregate({
+    where: { userId, timestamp: { gte: today } },
+    _sum: { cost: true },
+  });
+
+  if ((dailyUsage._sum.cost || 0) + estimatedCost > dailyLimit) {
+    throw new Error('Daily AI budget exceeded');
+  }
+
+  // Similar check for monthly
+}
+```
+
+### Global budget circuit breaker
+
+```typescript
+async function checkGlobalBudget(estimatedCost: number) {
+  const monthlyBudget = 500.00;  // $500/month total
+
+  const monthStart = new Date();
+  monthStart.setDate(1);
+  monthStart.setHours(0, 0, 0, 0);
+
+  const monthlyUsage = await db.aiUsage.aggregate({
+    where: { timestamp: { gte: monthStart } },
+    _sum: { cost: true },
+  });
+
+  if ((monthlyUsage._sum.cost || 0) + estimatedCost > monthlyBudget) {
+    // CIRCUIT BREAKER: Disable AI features
+    await disableAIFeatures();
+    await alertAdmins('AI budget exceeded - features disabled');
+    throw new Error('Service temporarily unavailable');
+  }
+}
+```
+
+---
+
+## Layer 4: Provider-Side Limits
+
+### OpenAI usage limits
+
+1. Go to platform.openai.com
+2. Settings > Limits
+3. Set monthly hard limit
+
+### Anthropic usage limits
+
+1. Go to console.anthropic.com
+2. Settings > Usage Limits
+3. Set spend limits
+
+### Set up billing alerts
+
+Most providers support alerts at:
+- 50% of budget
+- 80% of budget
+- 100% of budget
+
+---
+
+## Layer 5: Monitoring & Alerts
+
+### Real-time usage dashboard
+
+```typescript
+// Track key metrics
+const metrics = {
+  requestsPerMinute: await getRequestsPerMinute(),
+  costToday: await getCostToday(),
+  costThisMonth: await getCostThisMonth(),
+  topUsers: await getTopUsersByUsage(),
+  errorRate: await getErrorRate(),
+};
+```
+
+### Alert on anomalies
+
+```typescript
+async function checkForAnomalies() {
+  // Alert if hourly cost exceeds normal
+  const hourlyCost = await getHourlyCost();
+  const avgHourlyCost = await getAvgHourlyCost();
+
+  if (hourlyCost > avgHourlyCost * 3) {
+    await sendAlert({
+      type: 'anomaly',
+      message: `Hourly AI cost spike: $${hourlyCost} (avg: $${avgHourlyCost})`,
+      severity: 'high',
+    });
+  }
+
+  // Alert if single user is abusing
+  const topUser = await getTopUserThisHour();
+  if (topUser.requests > 100) {
+    await sendAlert({
+      type: 'abuse',
+      message: `User ${topUser.id} made ${topUser.requests} AI requests this hour`,
+      severity: 'medium',
+    });
+  }
+}
+```
+
+---
+
+## Cost Comparison: Models
+
+| Model | Input ($/1M tokens) | Output ($/1M tokens) | Best For |
+|-------|---------------------|----------------------|----------|
+| GPT-4 | $30 | $60 | Complex tasks |
+| GPT-4 Turbo | $10 | $30 | Long context |
+| GPT-3.5 Turbo | $0.50 | $1.50 | Simple tasks |
+| Claude 3 Opus | $15 | $75 | Highest quality |
+| Claude 3 Sonnet | $3 | $15 | Balanced |
+| Claude 3 Haiku | $0.25 | $1.25 | Speed/cost |
+
+**Tip:** Use cheaper models for simple tasks, reserve expensive models for complex ones.
+
+```typescript
+function selectModel(task: string) {
+  const simpleTasks = ['summarize', 'classify', 'extract'];
+  const complexTasks = ['code', 'analyze', 'create'];
+
+  if (simpleTasks.some(t => task.includes(t))) {
+    return 'gpt-3.5-turbo';  // Cheap and fast
+  }
+  return 'gpt-4-turbo';  // Better but pricier
+}
+```
+
+---
+
+## Quick Implementation Checklist
+
+1. [ ] API keys in server-side environment variables only
+2. [ ] Input length limits (e.g., 2000 chars)
+3. [ ] Output token limits (e.g., 500 tokens)
+4. [ ] Rate limiting per user (e.g., 10 requests/minute)
+5. [ ] Daily budget per user (e.g., $1/day)
+6. [ ] Global monthly budget with circuit breaker
+7. [ ] Provider-side hard limits configured
+8. [ ] Billing alerts at 50%, 80%, 100%
+9. [ ] Usage tracking in database
+10. [ ] Anomaly detection and alerting
+
+---
+
+**Remember: A $50,000 surprise bill is a real risk. Implement these layers before launch.**