@devwithbobby/loops 0.1.0 → 0.1.1

package/prds/SECURITY.md

@@ -1,246 +0,0 @@
-# Security Considerations for Loops Component
-
-## Current Security Risks
-
-### 1. ⚠️ **No Authentication/Authorization in Example**
-**Risk Level: HIGH**
-
-The example (`example/convex/example.ts`) exports all functions directly without authentication checks. This means:
-- Any authenticated user (or anyone with access) can send emails
-- Anyone can delete contacts
-- Anyone can unsubscribe users
-- No permission checks
-
-**Mitigation Required:**
-- Apps MUST wrap component functions with authentication
-- Add authorization checks before exposing functions to clients
-- Consider role-based access control
-
-### 2. ⚠️ **API Key Exposure Risk**
-**Risk Level: MEDIUM**
-
-The API key is passed through function arguments to component actions:
-- API keys appear in function arguments (could be logged)
-- Error messages might leak API key information
-- API key stored in memory in multiple places
-
-**Current Protection:**
-- API key is `private readonly` in client class
-- Stored in environment variables (not in code)
-- Only accessible from server-side code
-
-**Recommendations:**
-- Avoid logging function arguments
-- Sanitize error messages
-- Consider using Convex secrets management
-
-### 3. ⚠️ **Error Message Information Leakage**
-**Risk Level: MEDIUM**
-
-Error messages could expose sensitive information:
-```typescript
-throw new Error(`Loops API error: ${response.status} ${error}`);
-```
-- Could leak API details
-- Could expose internal structure
-
-**Recommendation:**
-- Sanitize error messages in production
-- Log detailed errors server-side only
-- Return generic error messages to clients
-
-### 4. ⚠️ **No Rate Limiting**
-**Risk Level: MEDIUM**
-
-Functions can be called unlimited times:
-- Could be abused to send spam
-- Could exhaust API quotas
-- Could cause DoS
-
-**Recommendation:**
-- Implement rate limiting in app wrapper functions
-- Use Convex rate limiting features
-- Consider per-user/per-IP limits
-
-### 5. ⚠️ **countContacts Query Exposed**
-**Risk Level: LOW-MEDIUM**
-
-The `countContacts` query can reveal user counts without authentication:
-- Anyone with app access can see audience sizes
-- Could be used for reconnaissance
-
-**Recommendation:**
-- Wrap in app function with auth
-- Consider if counts should be public information
-
-### 6. ✅ **Input Validation**
-**Status: GOOD**
-
-- Zod validation on all inputs
-- Email validation using `.email()` validator
-- Type safety enforced
-
-**Remaining Concerns:**
-- Ensure no email injection attacks
-- Validate event names and properties
-
-### 7. ✅ **Component Isolation**
-**Status: GOOD**
-
-- Component functions are internal (not directly callable from clients)
-- Apps must explicitly wrap functions
-- Follows Convex security model
-
-## Security Best Practices
-
-### ✅ What to Do:
-
-1. **Always Add Authentication in App Wrapper:**
-```typescript
-// ✅ GOOD - Add auth check
-export const addContact = action({
-  args: { email: v.string(), ... },
-  handler: async (ctx, args) => {
-    const identity = await ctx.auth.getUserIdentity();
-    if (!identity) throw new Error("Unauthorized");
-    
-    // Check permissions
-    if (!hasPermission(identity, "manageContacts")) {
-      throw new Error("Forbidden");
-    }
-    
-    return await loops.addContact(ctx, { email: args.email, ... });
-  },
-});
-```
-
-2. **Use Environment Variables for API Key:**
-```typescript
-// ✅ GOOD - API key from environment
-// Set LOOPS_API_KEY in Convex environment variables first:
-// npx convex env set LOOPS_API_KEY "your-api-key"
-const loops = new Loops(components.loopsComponent);
-// Uses process.env.LOOPS_API_KEY automatically
-
-// ❌ BAD - Never pass API key directly in production
-// const loops = new Loops(components.loopsComponent, { apiKey: "..." });
-```
-**📖 See [ENV_SETUP.md](./ENV_SETUP.md) for detailed setup instructions and security best practices.**
-
-3. **Sanitize Error Messages:**
-```typescript
-// ✅ GOOD - Generic error to client
-try {
-  await loops.addContact(ctx, contact);
-} catch (error) {
-  // Log detailed error server-side
-  console.error("Failed to add contact:", error);
-  // Return generic error to client
-  throw new Error("Failed to add contact. Please try again.");
-}
-```
-
-4. **Implement Rate Limiting:**
-```typescript
-import { rateLimit } from "convex-helpers/server/rateLimit";
-
-export const sendTransactional = action({
-  args: { ... },
-  handler: async (ctx, args) => {
-    await rateLimit(ctx, { maxOps: 10, period: 60000 }); // 10 per minute
-    return await loops.sendTransactional(ctx, args);
-  },
-});
-```
-
-5. **Validate User Permissions:**
-```typescript
-export const deleteContact = action({
-  args: { email: v.string() },
-  handler: async (ctx, args) => {
-    const identity = await ctx.auth.getUserIdentity();
-    if (!identity) throw new Error("Unauthorized");
-    
-    // Only admins can delete contacts
-    if (!isAdmin(identity)) {
-      throw new Error("Only admins can delete contacts");
-    }
-    
-    return await loops.deleteContact(ctx, args.email);
-  },
-});
-```
-
-### ❌ What NOT to Do:
-
-1. **Don't Export Functions Directly Without Auth:**
-```typescript
-// ❌ BAD - No authentication
-export const { addContact, deleteContact } = loops.api();
-```
-
-2. **Don't Pass API Key from Client:**
-```typescript
-// ❌ BAD - Never do this
-export const addContact = action({
-  args: { apiKey: v.string(), ... }, // Never accept API key from client
-  handler: async (ctx, args) => { ... }
-});
-```
-
-3. **Don't Expose Internal Errors:**
-```typescript
-// ❌ BAD - Exposes internal details
-catch (error) {
-  throw new Error(`API call failed: ${error.message} with key ${apiKey}`);
-}
-```
-
-4. **Don't Skip Rate Limiting for Email Sending:**
-```typescript
-// ❌ BAD - No rate limiting
-export const sendCampaign = action({
-  handler: async (ctx, args) => {
-    // Anyone could spam unlimited emails!
-    return await loops.sendCampaign(ctx, args);
-  },
-});
-```
-
-## Recommended Security Architecture
-
-```
-Client (React)
-    ↓
-App Function (with auth, rate limiting, validation)
-    ↓
-Loops Client (with API key from env)
-    ↓
-Component Function (validates input)
-    ↓
-Loops.so API
-```
-
-## Security Checklist for Apps Using This Component
-
-- [ ] Wrap all functions with authentication checks
-- [ ] Add authorization checks (role-based if needed)
-- [x] Implement rate limiting for email-sending functions - ✅ **IMPLEMENTED** See RATE_LIMITING.md
-- [ ] Sanitize error messages before returning to clients
-- [x] Store API key in Convex environment variables only - ✅ **IMPLEMENTED** See ENV_SETUP.md
-- [ ] Audit who can access contact management functions
-- [ ] Consider logging all email operations for audit trail
-- [ ] Validate user permissions for sensitive operations (delete, unsubscribe)
-- [x] Monitor for unusual activity (spam patterns) - ✅ **IMPLEMENTED** See MONITORING.md
-
-## Component-Level Security
-
-The component itself is secure because:
-- ✅ Functions are internal (not directly callable from clients)
-- ✅ Input validation with Zod
-- ✅ Type safety enforced
-- ✅ Component isolation prevents unauthorized access
-- ✅ API key never exposed to client code
-
-However, **apps using this component MUST implement their own security layer** when exposing functions to clients.
-