@xenterprises/fastify-xhubspot 1.0.0

package/SECURITY.md

@@ -0,0 +1,1078 @@
+# Security Guidelines for xHubspot
+
+This document provides comprehensive security guidance for using the xHubspot Fastify plugin with HubSpot's CRM API. Follow these guidelines to protect your data and ensure secure integration.
+
+## Table of Contents
+
+1. [API Key Management](#api-key-management)
+2. [Authentication & Authorization](#authentication--authorization)
+3. [Data Protection & Privacy](#data-protection--privacy)
+4. [Webhook Security](#webhook-security)
+5. [Request Validation & Sanitization](#request-validation--sanitization)
+6. [Error Handling & Logging](#error-handling--logging)
+7. [Rate Limiting & DOS Protection](#rate-limiting--dos-protection)
+8. [Network Security](#network-security)
+9. [Third-Party Portal Integration](#third-party-portal-integration)
+10. [Compliance & Regulations](#compliance--regulations)
+
+---
+
+## 1. API Key Management
+
+### 1.1 Token Generation & Storage
+
+**DO:**
+- Create Private App Access Tokens with minimal required scopes
+- Store tokens in environment variables (never hardcode)
+- Use `.env.local` for local development (never commit to version control)
+- Rotate tokens every 90 days minimum
+- Use different tokens for development, staging, and production
+
+**DON'T:**
+- Commit `.env` or token files to version control
+- Share tokens via email, Slack, or chat
+- Log tokens in application logs
+- Use the same token across multiple environments
+- Create tokens with all available scopes
+
+### 1.2 Required OAuth Scopes
+
+Only request scopes needed for your use case:
+
+```
+Minimum for contact management:
+- crm.objects.contacts.read
+- crm.objects.contacts.write
+
+Minimum for company/deal management:
+- crm.objects.companies.read
+- crm.objects.companies.write
+- crm.objects.deals.read
+- crm.objects.deals.write
+
+For custom objects:
+- crm.objects.custom.read
+- crm.objects.custom.write
+```
+
+Avoid requesting:
+- `crm.lists.read` / `crm.lists.write` - Only if absolutely necessary
+- `crm.quotes.*` - Unless specifically needed
+- `crm.pipelines.*` - Unless modifying pipelines
+- `actions:*` - Administrative scope
+
+### 1.3 Token Validation
+
+```javascript
+// BAD: Token validation only on startup
+async function xHubspot(fastify, options) {
+  const hubspot = new Client({ accessToken: options.apiKey });
+  // No token validation - fails silently
+}
+
+// GOOD: Comprehensive token validation
+async function xHubspot(fastify, options) {
+  const { apiKey, logRequests = false } = options;
+
+  if (!apiKey || apiKey.trim().length === 0) {
+    throw new Error("HubSpot API Key is required and cannot be empty");
+  }
+
+  if (!apiKey.startsWith("pat-")) {
+    fastify.log.warn("⚠️  Provided API key does not match HubSpot Private App pattern");
+  }
+
+  const hubspot = new Client({ accessToken: apiKey });
+
+  // Test token validity with a minimal read operation
+  try {
+    await hubspot.crm.contacts.basicApi.getPage({ limit: 1 });
+    fastify.log.info("✅ HubSpot API token validated successfully");
+  } catch (error) {
+    if (error.status === 401) {
+      throw new Error("HubSpot API token is invalid or expired");
+    }
+    throw error;
+  }
+}
+```
+
+---
+
+## 2. Authentication & Authorization
+
+### 2.1 Access Control in Third-Party Portals
+
+When integrating xHubspot with third-party portals:
+
+```javascript
+// BAD: No authorization checks
+fastify.post("/api/contacts", async (request, reply) => {
+  const contact = await fastify.contacts.create(request.body);
+  return contact;
+});
+
+// GOOD: Verify user authorization
+fastify.post("/api/contacts", async (request, reply) => {
+  // 1. Verify user authentication
+  if (!request.user) {
+    return reply.status(401).send({ error: "Unauthorized" });
+  }
+
+  // 2. Verify user authorization for this operation
+  if (!request.user.permissions.includes("contacts:write")) {
+    return reply.status(403).send({ error: "Forbidden" });
+  }
+
+  // 3. Verify contact ownership/access
+  const contact = await fastify.contacts.create(request.body);
+  return contact;
+});
+```
+
+### 2.2 Role-Based Access Control (RBAC)
+
+Implement granular permission checks:
+
+```javascript
+const permissions = {
+  "contacts:read": ["getById", "getByEmail", "list", "search"],
+  "contacts:write": ["create", "update", "batchCreate", "batchUpdate"],
+  "contacts:delete": ["delete"],
+  "companies:read": ["getById", "list"],
+  "companies:write": ["create", "update"],
+  "engagement:write": ["createNote", "createTask", "createCall", "createEmail"],
+};
+
+// Verify permission before allowing operation
+async function checkPermission(user, service, method) {
+  const allowedServices = permissions[`${service}:write`] || [];
+  if (!allowedServices.includes(method)) {
+    throw new Error(`User lacks permission for ${service}.${method}`);
+  }
+}
+```
+
+### 2.3 Session Management
+
+```javascript
+// Use secure session configuration
+fastify.register(require("@fastify/session"), {
+  secret: process.env.SESSION_SECRET,
+  cookie: {
+    secure: process.env.NODE_ENV === "production", // HTTPS only in production
+    httpOnly: true, // Prevent JavaScript access
+    sameSite: "strict", // CSRF protection
+    maxAge: 3600000, // 1 hour
+  },
+});
+```
+
+---
+
+## 3. Data Protection & Privacy
+
+### 3.1 Sensitive Data Handling
+
+**Sensitive fields in HubSpot:**
+- Email addresses
+- Phone numbers
+- Social security numbers
+- Payment card information
+- Home addresses
+
+```javascript
+// BAD: Logging sensitive data
+if (logRequests) {
+  console.log("Creating contact:", contactData);
+  // Outputs: { email: 'john@example.com', phone: '+1234567890' }
+}
+
+// GOOD: Mask sensitive data before logging
+function maskSensitiveData(data) {
+  const masked = { ...data };
+  if (masked.email) {
+    masked.email = masked.email.replace(/(.{2})(.*)(.{2})/, "$1****$3");
+  }
+  if (masked.phone) {
+    masked.phone = masked.phone.replace(/\d(?=\d{4})/g, "*");
+  }
+  return masked;
+}
+
+if (logRequests) {
+  console.log("Creating contact:", maskSensitiveData(contactData));
+  // Outputs: { email: 'jo****om', phone: '****7890' }
+}
+```
+
+### 3.2 Encryption in Transit
+
+```javascript
+// HTTPS is mandatory for all production requests
+const fastify = Fastify({
+  https: {
+    key: fs.readFileSync("./private-key.pem"),
+    cert: fs.readFileSync("./certificate.pem"),
+  },
+});
+
+// Verify TLS version 1.2 minimum
+// Node.js default is TLS 1.2+, but verify in headers
+fastify.register(require("@fastify/helmet"), {
+  contentSecurityPolicy: false,
+  strictTransportSecurity: {
+    maxAge: 31536000, // 1 year
+    includeSubDomains: true,
+    preload: true,
+  },
+});
+```
+
+### 3.3 Data Minimization
+
+Only retrieve properties you need:
+
+```javascript
+// BAD: Request all properties
+const contact = await fastify.contacts.getById(contactId);
+
+// GOOD: Request only necessary properties
+const contact = await fastify.contacts.getById(contactId, [
+  "firstname",
+  "lastname",
+  "email",
+  "phone",
+]);
+```
+
+### 3.4 GDPR & Privacy Compliance
+
+```javascript
+// Right to be forgotten - delete contact data
+async function deleteContact(contactId) {
+  // 1. Log the deletion request for audit trail
+  auditLog.record({
+    action: "DELETE_CONTACT",
+    contactId,
+    timestamp: new Date(),
+    reason: "GDPR Right to Deletion",
+  });
+
+  // 2. Delete from HubSpot
+  await fastify.contacts.delete(contactId);
+
+  // 3. Delete from local cache/database
+  await db.contacts.delete(contactId);
+
+  // 4. Verify deletion
+  try {
+    await fastify.contacts.getById(contactId);
+    throw new Error("Contact deletion failed - data still exists");
+  } catch (error) {
+    if (error.status === 404) {
+      // Expected - contact successfully deleted
+    }
+  }
+}
+
+// Right to access - provide contact data
+async function getContactData(contactId) {
+  const contact = await fastify.contacts.getById(contactId, null);
+  const engagements = await fastify.engagement.getEngagements({
+    contactId,
+  });
+  const associations = await fastify.contacts.getAssociations(contactId);
+
+  return {
+    personalData: contact,
+    engagementHistory: engagements,
+    associations,
+    exportedAt: new Date().toISOString(),
+  };
+}
+```
+
+---
+
+## 4. Webhook Security
+
+### 4.1 Webhook Signature Validation
+
+HubSpot signs webhooks with an HMAC-SHA256 signature. Always validate:
+
+```javascript
+import crypto from "crypto";
+
+function validateWebhookSignature(request, secret) {
+  const signature = request.headers["x-hubspot-request-signature"];
+  const timestamp = request.headers["x-hubspot-request-timestamp"];
+
+  if (!signature || !timestamp) {
+    throw new Error("Missing webhook signature or timestamp");
+  }
+
+  // Prevent replay attacks - signature must be recent (within 5 minutes)
+  const webhookTime = parseInt(timestamp);
+  const currentTime = Math.floor(Date.now() / 1000);
+  if (Math.abs(webhookTime - currentTime) > 300) {
+    throw new Error("Webhook timestamp too old - possible replay attack");
+  }
+
+  // Reconstruct the signature
+  const stringToSign = `${timestamp}${JSON.stringify(request.body)}`;
+  const expectedSignature = crypto
+    .createHmac("sha256", secret)
+    .update(stringToSign)
+    .digest("hex");
+
+  // Constant-time comparison to prevent timing attacks
+  if (
+    !crypto.timingSafeEqual(
+      Buffer.from(signature),
+      Buffer.from(expectedSignature)
+    )
+  ) {
+    throw new Error("Invalid webhook signature");
+  }
+
+  return true;
+}
+
+// Usage in Fastify hook
+fastify.post("/webhooks/hubspot", async (request, reply) => {
+  try {
+    validateWebhookSignature(
+      request,
+      process.env.HUBSPOT_WEBHOOK_SECRET
+    );
+  } catch (error) {
+    fastify.log.error("Webhook validation failed:", error.message);
+    return reply.status(401).send({ error: "Unauthorized" });
+  }
+
+  // Process webhook...
+});
+```
+
+### 4.2 Webhook Event Filtering
+
+```javascript
+// Only subscribe to necessary events
+const ALLOWED_EVENTS = [
+  "contact.creation",
+  "contact.change",
+  "deal.creation",
+  "deal.change",
+];
+
+fastify.post("/webhooks/hubspot", async (request, reply) => {
+  const { eventType } = request.body;
+
+  // Reject unexpected events
+  if (!ALLOWED_EVENTS.includes(eventType)) {
+    fastify.log.warn(`Received unexpected event: ${eventType}`);
+    return reply.status(202).send({ received: true });
+  }
+
+  // Process whitelisted events
+  await handleWebhookEvent(request.body);
+  reply.status(200).send({ success: true });
+});
+```
+
+### 4.3 Webhook Processing Best Practices
+
+```javascript
+// BAD: Blocking webhook processing
+fastify.post("/webhooks/hubspot", async (request, reply) => {
+  const result = await processWebhook(request.body); // Takes 30 seconds
+  reply.status(200).send(result);
+});
+
+// GOOD: Async webhook processing with immediate response
+fastify.post("/webhooks/hubspot", async (request, reply) => {
+  // Immediately acknowledge webhook
+  reply.status(202).send({ accepted: true });
+
+  // Process asynchronously in background
+  processWebhookAsync(request.body)
+    .catch((error) => {
+      fastify.log.error("Webhook processing failed:", error);
+      // Log to error tracking service (Sentry, etc.)
+    });
+});
+
+async function processWebhookAsync(event) {
+  // Add to queue for processing
+  await webhookQueue.add(event);
+}
+```
+
+---
+
+## 5. Request Validation & Sanitization
+
+### 5.1 Input Validation
+
+```javascript
+import { z } from "zod";
+
+const ContactSchema = z.object({
+  email: z.string().email().optional(),
+  firstname: z.string().max(50).optional(),
+  lastname: z.string().max(50).optional(),
+  phone: z.string().regex(/^\+?[0-9\s\-()]+$/).optional(),
+  hs_lead_status: z.enum(["NEW", "OPEN", "IN_PROGRESS", "OPEN_DEAL"]).optional(),
+});
+
+// Validate before creating contact
+fastify.post("/api/contacts", async (request, reply) => {
+  try {
+    const validatedData = ContactSchema.parse(request.body);
+    const contact = await fastify.contacts.create(validatedData);
+    return contact;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return reply.status(400).send({
+        error: "Validation failed",
+        details: error.errors,
+      });
+    }
+    throw error;
+  }
+});
+```
+
+### 5.2 Email Validation
+
+```javascript
+import { z } from "zod";
+
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const BLOCKED_DOMAINS = [
+  "test.com",
+  "example.com",
+  "localhost",
+  "invalid.com",
+];
+
+function validateEmail(email) {
+  if (!EMAIL_REGEX.test(email)) {
+    throw new Error("Invalid email format");
+  }
+
+  const [, domain] = email.split("@");
+  if (BLOCKED_DOMAINS.includes(domain.toLowerCase())) {
+    throw new Error("Email domain is blocked");
+  }
+
+  return true;
+}
+
+// Usage
+fastify.post("/api/contacts", async (request, reply) => {
+  if (request.body.email) {
+    validateEmail(request.body.email);
+  }
+  const contact = await fastify.contacts.create(request.body);
+  return contact;
+});
+```
+
+### 5.3 Phone Number Validation
+
+```javascript
+import libphonenumber from "libphonenumber-js";
+
+function validatePhoneNumber(phone, defaultCountry = "US") {
+  try {
+    const number = libphonenumber(phone, defaultCountry);
+    if (!number || !number.isValid()) {
+      throw new Error("Invalid phone number");
+    }
+    return number.format("E.164"); // +1234567890
+  } catch (error) {
+    throw new Error("Phone number validation failed");
+  }
+}
+
+// Usage
+fastify.post("/api/contacts", async (request, reply) => {
+  if (request.body.phone) {
+    request.body.phone = validatePhoneNumber(request.body.phone);
+  }
+  const contact = await fastify.contacts.create(request.body);
+  return contact;
+});
+```
+
+### 5.4 SQL/NoSQL Injection Prevention
+
+Use the HubSpot client library properly - never build queries manually:
+
+```javascript
+// BAD: Manual query building (never do this)
+const query = `contacts with email = '${userInput}'`;
+
+// GOOD: Use library's built-in methods
+const contact = await fastify.contacts.getByEmail(userInput);
+
+// GOOD: Use proper filtering with the API
+const contacts = await fastify.contacts.search("email", userInput);
+```
+
+---
+
+## 6. Error Handling & Logging
+
+### 6.1 Secure Error Messages
+
+```javascript
+// BAD: Exposing internal error details
+fastify.post("/api/contacts", async (request, reply) => {
+  try {
+    const contact = await fastify.contacts.create(request.body);
+    return contact;
+  } catch (error) {
+    return reply.status(500).send({
+      error: error.message, // Exposes HubSpot API details!
+      stack: error.stack,   // Exposes internal paths
+    });
+  }
+});
+
+// GOOD: Generic user-facing errors with detailed internal logging
+fastify.post("/api/contacts", async (request, reply) => {
+  try {
+    const contact = await fastify.contacts.create(request.body);
+    return contact;
+  } catch (error) {
+    // Log full details for debugging
+    fastify.log.error({
+      message: "Contact creation failed",
+      error: error.message,
+      stack: error.stack,
+      correlationId: error.correlationId,
+    });
+
+    // Return generic error to user
+    const status = error.status || 500;
+    return reply.status(status).send({
+      error: "An error occurred. Please contact support.",
+      correlationId: error.correlationId, // For support inquiries
+    });
+  }
+});
+```
+
+### 6.2 Structured Logging
+
+```javascript
+// Use structured logging for security events
+function logSecurityEvent(fastify, event, details) {
+  fastify.log.info({
+    type: "SECURITY_EVENT",
+    event,
+    timestamp: new Date().toISOString(),
+    ...details,
+  });
+}
+
+// Usage
+if (!request.user) {
+  logSecurityEvent(fastify, "UNAUTHORIZED_ACCESS", {
+    endpoint: request.url,
+    ip: request.ip,
+    headers: request.headers,
+  });
+  return reply.status(401).send({ error: "Unauthorized" });
+}
+
+if (!hasPermission) {
+  logSecurityEvent(fastify, "FORBIDDEN_ACCESS", {
+    userId: request.user.id,
+    endpoint: request.url,
+    requiredPermission,
+    userPermissions: request.user.permissions,
+  });
+  return reply.status(403).send({ error: "Forbidden" });
+}
+```
+
+### 6.3 Never Log Sensitive Data
+
+```javascript
+// Configuration for xHubspot
+const config = {
+  apiKey: process.env.HUBSPOT_ACCESS_TOKEN,
+  logRequests: process.env.HUBSPOT_LOG_REQUESTS === "true",
+  logSensitiveData: false, // ALWAYS false in production
+};
+
+// Sensitive fields to never log
+const SENSITIVE_FIELDS = [
+  "email",
+  "phone",
+  "ssn",
+  "creditcard",
+  "bankaccount",
+  "password",
+  "apiKey",
+  "accessToken",
+];
+
+function sanitizeForLogging(data) {
+  const sanitized = JSON.parse(JSON.stringify(data));
+
+  function mask(obj) {
+    if (typeof obj !== "object" || obj === null) return;
+    for (const key in obj) {
+      if (SENSITIVE_FIELDS.some((field) => key.toLowerCase().includes(field))) {
+        obj[key] = "***REDACTED***";
+      } else if (typeof obj[key] === "object") {
+        mask(obj[key]);
+      }
+    }
+  }
+
+  mask(sanitized);
+  return sanitized;
+}
+```
+
+---
+
+## 7. Rate Limiting & DOS Protection
+
+### 7.1 HubSpot API Rate Limiting
+
+```javascript
+// Configure rate limiting based on your HubSpot tier
+const RATE_LIMITS = {
+  free: 10, // requests per second
+  professional: 100,
+  enterprise: 500,
+};
+
+// Use the configured rate limit
+const config = {
+  rateLimit: process.env.HUBSPOT_RATE_LIMIT || RATE_LIMITS.free,
+  maxRetries: parseInt(process.env.HUBSPOT_MAX_RETRIES || "3"),
+  retryDelay: parseInt(process.env.HUBSPOT_RETRY_DELAY || "1000"),
+};
+
+// Implement backoff strategy for rate limit errors
+async function withRetry(fn, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (error.status === 429) {
+        // Rate limited
+        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+        fastify.log.warn(
+          `Rate limited. Retrying after ${delay}ms (attempt ${attempt}/${maxRetries})`
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+```
+
+### 7.2 Application-Level Rate Limiting
+
+```javascript
+import fastifyRateLimit from "@fastify/rate-limit";
+
+fastify.register(fastifyRateLimit, {
+  max: 100, // Max requests per window
+  timeWindow: "15 minutes",
+  cache: 10000, // Number of records to store
+  allowList: ["127.0.0.1"], // Whitelist IPs
+  redis: process.env.REDIS_URL, // Optional: use Redis for distributed rate limiting
+});
+```
+
+### 7.3 Batch Operation Limits
+
+```javascript
+// Enforce HubSpot's batch limits
+const BATCH_SIZE_LIMITS = {
+  contacts: 100,
+  companies: 100,
+  deals: 100,
+};
+
+fastify.post("/api/contacts/batch", async (request, reply) => {
+  const { contacts } = request.body;
+
+  if (!Array.isArray(contacts)) {
+    return reply.status(400).send({ error: "Expected array of contacts" });
+  }
+
+  if (contacts.length > BATCH_SIZE_LIMITS.contacts) {
+    return reply.status(400).send({
+      error: `Batch size exceeds maximum of ${BATCH_SIZE_LIMITS.contacts}`,
+    });
+  }
+
+  const result = await fastify.contacts.batchCreate(contacts);
+  return result;
+});
+```
+
+---
+
+## 8. Network Security
+
+### 8.1 CORS Configuration
+
+```javascript
+import fastifyCors from "@fastify/cors";
+
+fastify.register(fastifyCors, {
+  origin: process.env.ALLOWED_ORIGINS?.split(",") || ["https://app.example.com"],
+  credentials: true,
+  methods: ["GET", "POST", "PUT", "DELETE"],
+  allowedHeaders: ["Content-Type", "Authorization"],
+});
+```
+
+### 8.2 HTTPS Enforcement
+
+```javascript
+fastify.register(require("@fastify/helmet"), {
+  strictTransportSecurity: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true,
+  },
+  frameguard: {
+    action: "deny", // Prevent clickjacking
+  },
+  noSniff: true,
+  xssFilter: true,
+});
+
+// Redirect HTTP to HTTPS in production
+if (process.env.NODE_ENV === "production") {
+  fastify.register(require("@fastify/https-redirect"));
+}
+```
+
+### 8.3 VPN/IP Whitelisting
+
+```javascript
+// Optional: Restrict API access to specific IPs
+const ALLOWED_IPS = (process.env.HUBSPOT_ALLOWED_IPS || "").split(",").filter(Boolean);
+
+fastify.addHook("preHandler", async (request, reply) => {
+  if (ALLOWED_IPS.length > 0) {
+    const clientIP = request.ip;
+    if (!ALLOWED_IPS.includes(clientIP)) {
+      fastify.log.warn(`Access denied from IP: ${clientIP}`);
+      return reply.status(403).send({ error: "Forbidden" });
+    }
+  }
+});
+```
+
+---
+
+## 9. Third-Party Portal Integration
+
+### 9.1 Portal Authentication
+
+```javascript
+// Implement JWT-based authentication for portal
+import jwt from "@fastify/jwt";
+
+fastify.register(jwt, {
+  secret: process.env.JWT_SECRET,
+  sign: { expiresIn: "24h" },
+});
+
+// Login endpoint
+fastify.post("/auth/login", async (request, reply) => {
+  const { username, password } = request.body;
+
+  // Verify credentials (example with bcrypt)
+  const user = await verifyCredentials(username, password);
+
+  if (!user) {
+    return reply.status(401).send({ error: "Invalid credentials" });
+  }
+
+  const token = fastify.jwt.sign({
+    userId: user.id,
+    username: user.username,
+    permissions: user.permissions,
+  });
+
+  return { token };
+});
+
+// Protect routes with authentication
+fastify.post("/api/contacts", async (request, reply) => {
+  try {
+    await request.jwtVerify();
+  } catch (error) {
+    return reply.status(401).send({ error: "Unauthorized" });
+  }
+
+  const contact = await fastify.contacts.create(request.body);
+  return contact;
+});
+```
+
+### 9.2 Portal Data Isolation
+
+```javascript
+// Ensure portal users only access their own data
+async function getPortalUserContacts(userId) {
+  // Get contacts associated with this portal user
+  const contacts = await db.contacts.find({ portalUserId: userId });
+  return contacts;
+}
+
+// Verify access before returning data
+fastify.get("/api/contacts/:id", async (request, reply) => {
+  const { id } = request.params;
+  const { userId } = request.user;
+
+  const contact = await fastify.contacts.getById(id);
+
+  // Verify the user owns this contact
+  const ownership = await db.contacts.verify(id, userId);
+  if (!ownership) {
+    return reply.status(403).send({ error: "Forbidden" });
+  }
+
+  return contact;
+});
+```
+
+### 9.3 Audit Logging for Portal Actions
+
+```javascript
+// Log all portal actions for compliance
+async function logPortalAction(userId, action, resourceId, details) {
+  await db.auditLog.create({
+    userId,
+    action,
+    resourceId,
+    timestamp: new Date(),
+    ipAddress: details.ip,
+    userAgent: details.userAgent,
+    changes: details.changes,
+  });
+}
+
+fastify.post("/api/contacts", async (request, reply) => {
+  const contact = await fastify.contacts.create(request.body);
+
+  await logPortalAction(request.user.id, "CREATE_CONTACT", contact.id, {
+    ip: request.ip,
+    userAgent: request.headers["user-agent"],
+    changes: request.body,
+  });
+
+  return contact;
+});
+```
+
+---
+
+## 10. Compliance & Regulations
+
+### 10.1 GDPR Compliance
+
+**Data Processing Agreement (DPA):**
+- Ensure you have a DPA with HubSpot
+- Document all data processing activities
+- Implement data retention policies
+
+**User Rights:**
+- **Right to Access:** Implement endpoint to export user data
+- **Right to Erasure:** Implement contact deletion with audit trail
+- **Right to Rectification:** Allow contact data updates
+- **Right to Data Portability:** Export contact data in standard format
+
+```javascript
+// Implement GDPR data export endpoint
+fastify.get("/api/user/data-export", async (request, reply) => {
+  const userId = request.user.id;
+
+  // Gather all user data
+  const contactData = await getContactData(userId);
+  const engagementData = await getEngagementData(userId);
+  const auditLog = await getAuditLog(userId);
+
+  // Return as JSON for portability
+  return {
+    exportDate: new Date().toISOString(),
+    dataSubject: userId,
+    contacts: contactData,
+    engagements: engagementData,
+    auditLog,
+  };
+});
+
+// Implement right to erasure
+fastify.delete("/api/user/data", async (request, reply) => {
+  const userId = request.user.id;
+
+  // Request confirmation
+  if (!request.body.confirmDeletion) {
+    return reply.status(400).send({
+      error: "Data deletion must be confirmed",
+    });
+  }
+
+  // Log deletion request
+  await logPortalAction(userId, "DATA_DELETION_REQUEST", userId, {
+    ip: request.ip,
+    reason: "GDPR Right to Erasure",
+  });
+
+  // Delete all associated data
+  const contacts = await getPortalUserContacts(userId);
+  for (const contact of contacts) {
+    await fastify.contacts.delete(contact.id);
+  }
+
+  await db.user.delete(userId);
+
+  return { success: true, message: "All data has been deleted" };
+});
+```
+
+### 10.2 CCPA Compliance (California)
+
+Similar to GDPR but with specific timeline requirements:
+- Must provide data access within 45 days
+- Must allow "Do Not Sell My Personal Information" opt-out
+- Must not discriminate against users exercising rights
+
+### 10.3 Data Retention Policies
+
+```javascript
+// Implement automatic data retention/deletion
+const DATA_RETENTION_DAYS = parseInt(process.env.DATA_RETENTION_DAYS || "365");
+
+async function purgeOldContacts() {
+  const cutoffDate = new Date();
+  cutoffDate.setDate(cutoffDate.getDate() - DATA_RETENTION_DAYS);
+
+  const oldContacts = await db.contacts.find({
+    lastInteraction: { $lt: cutoffDate },
+    markedForDeletion: true,
+  });
+
+  for (const contact of oldContacts) {
+    await fastify.contacts.delete(contact.hubspotId);
+    await db.contacts.delete(contact.id);
+  }
+}
+
+// Run daily via cron job
+schedule.scheduleJob("0 2 * * *", purgeOldContacts); // 2 AM daily
+```
+
+### 10.4 Compliance Monitoring
+
+```javascript
+// Monitor for compliance violations
+async function monitorCompliance() {
+  // Check for suspicious activity
+  const suspiciousActivity = await db.auditLog.find({
+    action: "DELETE_CONTACT",
+    timestamp: { $gte: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+  });
+
+  if (suspiciousActivity.length > 100) {
+    // Alert security team
+    await sendSecurityAlert({
+      type: "HIGH_DELETION_VOLUME",
+      count: suspiciousActivity.length,
+      period: "24 hours",
+    });
+  }
+
+  // Check for compliance violations
+  const unencryptedTokens = await db.config.find({
+    field: "apiKey",
+    encrypted: false,
+  });
+
+  if (unencryptedTokens.length > 0) {
+    await sendSecurityAlert({
+      type: "UNENCRYPTED_SECRETS",
+      count: unencryptedTokens.length,
+    });
+  }
+}
+```
+
+---
+
+## Security Checklist
+
+Before deploying to production:
+
+- [ ] API key stored in environment variable, not hardcoded
+- [ ] Token rotation scheduled (every 90 days)
+- [ ] HTTPS/TLS enabled for all connections
+- [ ] Webhook signature validation implemented
+- [ ] Input validation and sanitization for all endpoints
+- [ ] Error messages don't expose internal details
+- [ ] Sensitive data never logged
+- [ ] Authentication and authorization implemented
+- [ ] Rate limiting configured
+- [ ] CORS configured with specific allowed origins
+- [ ] CSRF protection enabled
+- [ ] Audit logging implemented
+- [ ] Database backups configured
+- [ ] Security headers (CSP, HSTS, etc.) configured
+- [ ] Third-party dependencies up to date
+- [ ] Security testing completed
+- [ ] Incident response plan documented
+- [ ] Compliance requirements identified and implemented
+- [ ] Data retention policy defined
+- [ ] Privacy policy updated and compliant
+
+---
+
+## Incident Response
+
+If you suspect a security incident:
+
+1. **Immediately revoke the compromised API token** in HubSpot admin
+2. **Generate a new API token** with same scopes
+3. **Update environment variables** with new token
+4. **Review audit logs** for unauthorized access
+5. **Notify affected users** if personal data was exposed
+6. **File required notifications** with regulators (GDPR/CCPA)
+7. **Conduct root cause analysis** to prevent future incidents
+8. **Document incident** for compliance records
+
+---
+
+## Additional Resources
+
+- [HubSpot API Security](https://developers.hubspot.com/docs/api/overview)
+- [OWASP Top 10](https://owasp.org/Top10/)
+- [GDPR Compliance Guide](https://gdpr-info.eu/)
+- [CCPA Compliance Guide](https://www.ccpa.ca.gov/)
+- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
+- [Fastify Security](https://www.fastify.io/docs/latest/Guides/Security/)
+
+---
+
+**Last Updated:** 2025-12-29
+**Maintainer:** Tim Mushen
+**License:** ISC