perspectapi-ts-sdk 6.5.9 → 7.0.0

package/docs/v1-deprecated/legacy-docs/csrf-protection.md

@@ -0,0 +1,664 @@
+# CSRF Protection Guide
+
+> Deprecated v1 material. Do not copy these examples into new code. v1 sunsets
+> on 2026-06-01; use `createPerspectApiV2Client` from
+> `perspectapi-ts-sdk/v2` and `/api/v2`.
+
+Cross-Site Request Forgery (CSRF) protection is critical for web applications. This guide explains how to properly handle CSRF tokens with the PerspectAPI SDK.
+
+## Table of Contents
+
+- [Understanding CSRF](#understanding-csrf)
+- [When CSRF is Required](#when-csrf-is-required)
+- [Implementation Patterns](#implementation-patterns)
+- [Browser Applications](#browser-applications)
+- [Server-Side Applications](#server-side-applications)
+- [Mobile/Desktop Applications](#mobiledesktop-applications)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Understanding CSRF
+
+CSRF tokens prevent malicious websites from making unauthorized requests on behalf of your users. The security model ensures:
+
+1. **Token Generation**: Server generates a unique token tied to the user's session
+2. **Token Storage**: Your app stores it securely (NOT in localStorage)
+3. **Token Submission**: Your app includes it with state-changing requests
+4. **Token Validation**: Server validates the token matches
+
+## When CSRF is Required
+
+CSRF tokens are **REQUIRED** for:
+- Contact form submissions
+- Newsletter subscriptions
+- Any state-changing operations from browsers
+
+CSRF tokens are **NOT NEEDED** for:
+- Read-only operations (GET requests)
+- Server-to-server API calls (use API keys instead)
+- Mobile/desktop applications (no browser = no CSRF risk)
+
+## Implementation Patterns
+
+### ✅ CORRECT: Client Provides Token
+
+```typescript
+// GOOD: Client must obtain and provide token
+async submitContact(siteName, data, csrfToken) {
+  if (!csrfToken) {
+    throw new Error('CSRF token required');
+  }
+  return this.post('/contact', data, { csrfToken });
+}
+```
+
+## Browser Applications
+
+### 1. Server-Rendered HTML (Traditional)
+
+```html
+<!-- Token rendered in meta tag by server -->
+<meta name="csrf-token" content="<%= csrfToken %>" />
+
+<script>
+  // Get token from meta tag
+  const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
+  
+  // Use with SDK
+  const client = createPerspectApiClient({
+    baseUrl: 'https://api.example.com',
+    apiKey: 'public-key'
+  });
+  
+  // Submit with CSRF token
+  await client.contact.submitContact('my-site', formData, csrfToken);
+</script>
+```
+
+### 2. Single Page Application (SPA)
+
+```typescript
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+class App {
+  private client: PerspectApiClient;
+  private csrfToken: string | null = null;
+  
+  constructor() {
+    this.client = createPerspectApiClient({
+      baseUrl: process.env.REACT_APP_API_URL,
+      apiKey: process.env.REACT_APP_PUBLIC_KEY
+    });
+  }
+  
+  async initialize() {
+    // Fetch CSRF token once on app load
+    // IMPORTANT: Use same-origin to ensure token is tied to user's session
+    const response = await fetch('/api/v1/csrf/token/my-site', {
+      credentials: 'same-origin',  // Critical for security!
+      headers: {
+        'Accept': 'application/json'
+      }
+    });
+    
+    const data = await response.json();
+    this.csrfToken = data.csrf_token;
+    
+    // Store in memory only, never localStorage!
+    // Token should be re-fetched on page refresh
+  }
+  
+  async submitContactForm(formData: ContactFormData) {
+    if (!this.csrfToken) {
+      throw new Error('CSRF token not initialized');
+    }
+    
+    return await this.client.contact.submitContact(
+      'my-site',
+      formData,
+      this.csrfToken
+    );
+  }
+}
+```
+
+### 3. React Implementation
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+const client = createPerspectApiClient({
+  baseUrl: process.env.REACT_APP_API_URL!,
+  apiKey: process.env.REACT_APP_PUBLIC_KEY!
+});
+
+export function ContactForm() {
+  const [csrfToken, setCsrfToken] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  
+  useEffect(() => {
+    // Fetch CSRF token on component mount
+    async function fetchToken() {
+      try {
+        const response = await fetch(
+          `${process.env.REACT_APP_API_URL}/api/v1/csrf/token/${process.env.REACT_APP_SITE_NAME}`,
+          {
+            credentials: 'same-origin',
+            headers: { 'Accept': 'application/json' }
+          }
+        );
+        const data = await response.json();
+        setCsrfToken(data.csrf_token);
+      } catch (error) {
+        console.error('Failed to fetch CSRF token:', error);
+      } finally {
+        setIsLoading(false);
+      }
+    }
+    
+    fetchToken();
+  }, []);
+  
+  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    
+    if (!csrfToken) {
+      alert('Security token not loaded. Please refresh the page.');
+      return;
+    }
+    
+    const formData = new FormData(event.currentTarget);
+    
+    try {
+      const result = await client.contact.submitContact(
+        process.env.REACT_APP_SITE_NAME!,
+        {
+          name: formData.get('name') as string,
+          email: formData.get('email') as string,
+          message: formData.get('message') as string,
+        },
+        csrfToken  // Pass CSRF token
+      );
+      
+      alert('Message sent successfully!');
+    } catch (error) {
+      console.error('Submission failed:', error);
+      alert('Failed to send message. Please try again.');
+    }
+  };
+  
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="name" type="text" required />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send Message</button>
+    </form>
+  );
+}
+```
+
+### 4. Vue.js Implementation
+
+```vue
+<template>
+  <form @submit.prevent="submitForm">
+    <input v-model="form.name" type="text" required />
+    <input v-model="form.email" type="email" required />
+    <textarea v-model="form.message" required></textarea>
+    <button type="submit" :disabled="!csrfToken">
+      Send Message
+    </button>
+  </form>
+</template>
+
+<script>
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+export default {
+  data() {
+    return {
+      csrfToken: null,
+      form: {
+        name: '',
+        email: '',
+        message: ''
+      },
+      client: null
+    };
+  },
+  
+  async created() {
+    // Initialize client
+    this.client = createPerspectApiClient({
+      baseUrl: process.env.VUE_APP_API_URL,
+      apiKey: process.env.VUE_APP_PUBLIC_KEY
+    });
+    
+    // Fetch CSRF token
+    await this.fetchCsrfToken();
+  },
+  
+  methods: {
+    async fetchCsrfToken() {
+      try {
+        const response = await fetch(
+          `${process.env.VUE_APP_API_URL}/api/v1/csrf/token/${process.env.VUE_APP_SITE_NAME}`,
+          {
+            credentials: 'same-origin',
+            headers: { 'Accept': 'application/json' }
+          }
+        );
+        const data = await response.json();
+        this.csrfToken = data.csrf_token;
+      } catch (error) {
+        console.error('Failed to fetch CSRF token:', error);
+      }
+    },
+    
+    async submitForm() {
+      if (!this.csrfToken) {
+        alert('Security token not loaded');
+        return;
+      }
+      
+      try {
+        await this.client.contact.submitContact(
+          process.env.VUE_APP_SITE_NAME,
+          this.form,
+          this.csrfToken
+        );
+        
+        alert('Message sent!');
+        this.form = { name: '', email: '', message: '' };
+      } catch (error) {
+        alert('Failed to send message');
+      }
+    }
+  }
+};
+</script>
+```
+
+## Server-Side Applications
+
+### Next.js (App Router)
+
+```typescript
+// app/api/contact/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  
+  // Server-side: Use API key, no CSRF needed
+  const client = createPerspectApiClient({
+    baseUrl: process.env.PERSPECT_API_URL!,
+    apiKey: process.env.PERSPECT_API_KEY!  // Server-side API key
+  });
+  
+  try {
+    // No CSRF token needed for server-to-server calls
+    const result = await client.contact.submitContact(
+      process.env.SITE_NAME!,
+      body
+      // No CSRF token parameter
+    );
+    
+    return NextResponse.json(result);
+  } catch (error) {
+    return NextResponse.json(
+      { error: 'Submission failed' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Next.js (Pages Router with SSR)
+
+```tsx
+// pages/contact.tsx
+import { GetServerSideProps } from 'next';
+import { useState } from 'react';
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+interface Props {
+  csrfToken: string;
+}
+
+export const getServerSideProps: GetServerSideProps<Props> = async (context) => {
+  // Server-side: Fetch CSRF token
+  const response = await fetch(
+    `${process.env.API_URL}/api/v1/csrf/token/${process.env.SITE_NAME}`
+  );
+  const data = await response.json();
+  
+  return {
+    props: {
+      csrfToken: data.csrf_token
+    }
+  };
+};
+
+export default function ContactPage({ csrfToken }: Props) {
+  const [client] = useState(() => 
+    createPerspectApiClient({
+      baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+      apiKey: process.env.NEXT_PUBLIC_API_KEY!
+    })
+  );
+  
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    // ... get form data
+    
+    await client.contact.submitContact(
+      process.env.NEXT_PUBLIC_SITE_NAME!,
+      formData,
+      csrfToken  // Use server-provided token
+    );
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Token is already in memory, not in DOM */}
+      {/* Form fields... */}
+    </form>
+  );
+}
+```
+
+### Remix
+
+```tsx
+// app/routes/contact.tsx
+import { json, type ActionFunctionArgs } from "@remix-run/node";
+import { Form, useLoaderData } from "@remix-run/react";
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+export async function loader() {
+  // Fetch CSRF token server-side
+  const response = await fetch(
+    `${process.env.API_URL}/api/v1/csrf/token/${process.env.SITE_NAME}`
+  );
+  const data = await response.json();
+  
+  return json({ csrfToken: data.csrf_token });
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  const formData = await request.formData();
+  const csrfToken = formData.get("csrfToken") as string;
+  
+  const client = createPerspectApiClient({
+    baseUrl: process.env.API_URL!,
+    apiKey: process.env.API_KEY!
+  });
+  
+  await client.contact.submitContact(
+    process.env.SITE_NAME!,
+    {
+      name: formData.get("name") as string,
+      email: formData.get("email") as string,
+      message: formData.get("message") as string,
+    },
+    csrfToken
+  );
+  
+  return json({ success: true });
+}
+
+export default function Contact() {
+  const { csrfToken } = useLoaderData<typeof loader>();
+  
+  return (
+    <Form method="post">
+      <input type="hidden" name="csrfToken" value={csrfToken} />
+      <input name="name" type="text" required />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </Form>
+  );
+}
+```
+
+## Mobile/Desktop Applications
+
+CSRF tokens are **NOT NEEDED** for native applications:
+
+```typescript
+// React Native / Electron / Tauri
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+
+// No CSRF token needed - not running in a browser
+await client.contact.submitContact(
+  'my-site',
+  formData
+  // No CSRF parameter
+);
+
+// The SDK will detect it's not in a browser and won't warn
+```
+
+## Best Practices
+
+### 1. Token Storage
+
+```typescript
+// ✅ GOOD: Store in memory
+let csrfToken: string | null = null;
+
+// ✅ GOOD: Store in meta tag (server-rendered)
+<meta name="csrf-token" content={csrfToken} />
+
+// ❌ BAD: Never store in localStorage
+localStorage.setItem('csrf', token); // NO!
+
+// ❌ BAD: Never store in sessionStorage
+sessionStorage.setItem('csrf', token); // NO!
+```
+
+### 2. Token Fetching
+
+```typescript
+// ✅ GOOD: Fetch with credentials
+const response = await fetch('/api/v1/csrf/token/my-site', {
+  credentials: 'same-origin',  // Critical!
+  headers: { 'Accept': 'application/json' }
+});
+
+// ❌ BAD: Fetching without credentials
+const response = await fetch('/api/v1/csrf/token/my-site');
+// Token won't be tied to session!
+```
+
+### 3. Token Refresh
+
+```typescript
+class CSRFManager {
+  private token: string | null = null;
+  private tokenExpiry: number = 0;
+  
+  async getToken(): Promise<string> {
+    // Refresh if expired or not set
+    if (!this.token || Date.now() > this.tokenExpiry) {
+      const response = await fetch('/api/v1/csrf/token/my-site', {
+        credentials: 'same-origin'
+      });
+      const data = await response.json();
+      this.token = data.csrf_token;
+      // Token expires in 1 hour
+      this.tokenExpiry = Date.now() + 3600000;
+    }
+    
+    return this.token;
+  }
+  
+  clearToken() {
+    this.token = null;
+    this.tokenExpiry = 0;
+  }
+}
+```
+
+### 4. Error Handling
+
+```typescript
+async function submitWithCSRF(client, siteName, data) {
+  let csrfToken;
+  
+  try {
+    // Get CSRF token
+    const tokenResponse = await fetch(`/api/v1/csrf/token/${siteName}`, {
+      credentials: 'same-origin'
+    });
+    
+    if (!tokenResponse.ok) {
+      throw new Error('Failed to fetch CSRF token');
+    }
+    
+    const tokenData = await tokenResponse.json();
+    csrfToken = tokenData.csrf_token;
+  } catch (error) {
+    console.error('CSRF token fetch failed:', error);
+    throw new Error('Security verification failed. Please refresh and try again.');
+  }
+  
+  try {
+    // Submit with token
+    return await client.contact.submitContact(siteName, data, csrfToken);
+  } catch (error) {
+    if (error.status === 401 && error.message.includes('CSRF')) {
+      // Token might be expired, clear and retry once
+      const newToken = await fetchNewCSRFToken(siteName);
+      return await client.contact.submitContact(siteName, data, newToken);
+    }
+    throw error;
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "CSRF token required" Error
+
+**Cause**: Not passing CSRF token to methods that require it.
+
+**Solution**:
+```typescript
+// ❌ Wrong
+await client.contact.submitContact('my-site', data);
+
+// ✅ Correct
+await client.contact.submitContact('my-site', data, csrfToken);
+```
+
+#### 2. "Invalid CSRF token" Error
+
+**Causes**:
+- Token expired
+- Token not tied to user session
+- Wrong site name
+
+**Solution**:
+```typescript
+// Ensure credentials are sent
+fetch('/api/v1/csrf/token/my-site', {
+  credentials: 'same-origin'  // Required!
+});
+
+// Use correct site name
+const siteName = 'my-site';  // Must match your site configuration
+```
+
+#### 3. CORS Issues
+
+**Cause**: Cross-origin requests without proper configuration.
+
+**Solution**:
+```typescript
+// For cross-origin requests, configure CORS properly
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.example.com',
+  headers: {
+    'X-Requested-With': 'XMLHttpRequest'  // Sometimes helps with CORS
+  }
+});
+
+// And ensure API allows your origin
+```
+
+#### 4. Token Not Found in Response
+
+**Cause**: Using wrong endpoint or site not found.
+
+**Solution**:
+```typescript
+// Use site-specific endpoint for development
+const response = await fetch('/api/v1/csrf/token/my-site');
+const data = await response.json();
+const token = data.csrf_token;  // Note: csrf_token, not token
+
+// For production with custom domain
+const response = await fetch('/api/v1/csrf/token');
+// Requires proper Host header
+```
+
+## Security Checklist
+
+- [ ] Never auto-fetch CSRF tokens in the SDK
+- [ ] Always use `credentials: 'same-origin'` when fetching tokens
+- [ ] Store tokens in memory or meta tags, never localStorage
+- [ ] Pass CSRF tokens explicitly to SDK methods
+- [ ] Refresh tokens periodically (they expire)
+- [ ] Use HTTPS in production
+- [ ] Configure CORS properly for cross-origin requests
+- [ ] Use API keys for server-to-server calls instead of CSRF
+- [ ] Validate tokens server-side on all state-changing operations
+
+## Migration Guide
+
+If you're upgrading from a version without CSRF support:
+
+### Before (No CSRF)
+```typescript
+// Old version - no CSRF parameter
+await client.contact.submitContact('my-site', formData);
+```
+
+### After (With CSRF)
+```typescript
+// New version - CSRF token required for browser apps
+const csrfToken = await fetchCSRFToken('my-site');
+await client.contact.submitContact('my-site', formData, csrfToken);
+```
+
+### Backward Compatibility
+
+The CSRF token parameter is optional to maintain backward compatibility:
+- **Browser environments**: Will show a console warning if CSRF token is missing
+- **Node.js/Server environments**: No warning, CSRF not required
+- **Mobile/Desktop apps**: No warning, CSRF not required
+
+## Summary
+
+1. **Browser apps** must fetch and provide CSRF tokens
+2. **Server apps** use API keys, no CSRF needed
+3. **Mobile/Desktop apps** don't need CSRF tokens
+4. **Never** auto-fetch tokens in the SDK
+5. **Always** use `credentials: 'same-origin'`
+6. **Store** tokens in memory only
+7. **Pass** tokens explicitly to SDK methods