twinmind-security-basics

TwinMind Security Basics

Overview

Essential security practices for TwinMind integrations, focusing on API security, data privacy, and compliance.

Prerequisites

• TwinMind account configured
• Understanding of environment variables
• Basic security concepts

Instructions

Step 1: Secure API Key Management

// NEVER do this - hardcoded secrets
const TWINMIND_API_KEY = "tm_sk_abc123"; // BAD!

// DO this - use environment variables
const apiKey = process.env.TWINMIND_API_KEY;
if (!apiKey) {
  throw new Error('TWINMIND_API_KEY environment variable required');
}

// Even better - use a secrets manager
import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

async function getApiKey(): Promise<string> {
  const client = new SecretManagerServiceClient();
  const [version] = await client.accessSecretVersion({
    name: 'projects/my-project/secrets/twinmind-api-key/versions/latest',
  });
  return version.payload?.data?.toString() || '';
}

Step 2: Environment Configuration

# .env file (gitignored)
TWINMIND_API_KEY=tm_sk_your_secret_key
TWINMIND_WEBHOOK_SECRET=whsec_your_webhook_secret
TWINMIND_ENCRYPTION_KEY=your_32_byte_encryption_key

# .env.example (committed to repo - no real values)
TWINMIND_API_KEY=tm_sk_xxx
TWINMIND_WEBHOOK_SECRET=whsec_xxx
TWINMIND_ENCRYPTION_KEY=xxx

# .gitignore
.env
.env.local
.env.*.local
*.pem
*.key
secrets/

Step 3: Validate Webhook Signatures

// src/twinmind/webhooks/verify.ts
import crypto from 'crypto';

export function verifyWebhookSignature(
  payload: string | Buffer,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const providedSignature = signature.replace('sha256=', '');

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(providedSignature)
  );
}

// Express middleware
export function webhookMiddleware(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers['x-twinmind-signature'] as string;
  const secret = process.env.TWINMIND_WEBHOOK_SECRET!;

  if (!signature) {
    return res.status(401).json({ error: 'Missing signature' });
  }

  const rawBody = (req as any).rawBody || JSON.stringify(req.body);

  if (!verifyWebhookSignature(rawBody, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  next();
}

Step 4: Encrypt Sensitive Data at Rest

// src/twinmind/encryption.ts
import crypto from 'crypto';

const ALGORITHM = 'aes-256-gcm';
const IV_LENGTH = 16;
const TAG_LENGTH = 16;

export function encrypt(text: string, key: string): string {
  const iv = crypto.randomBytes(IV_LENGTH);
  const cipher = crypto.createCipheriv(
    ALGORITHM,
    Buffer.from(key, 'hex'),
    iv
  );

  let encrypted = cipher.update(text, 'utf8', 'hex');
  encrypted += cipher.final('hex');

  const tag = cipher.getAuthTag();

  // Return iv:tag:encrypted
  return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted}`;
}

export function decrypt(encryptedData: string, key: string): string {
  const [ivHex, tagHex, encrypted] = encryptedData.split(':');

  const iv = Buffer.from(ivHex, 'hex');
  const tag = Buffer.from(tagHex, 'hex');
  const decipher = crypto.createDecipheriv(
    ALGORITHM,
    Buffer.from(key, 'hex'),
    iv
  );

  decipher.setAuthTag(tag);

  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');

  return decrypted;
}

// Usage for storing transcripts
export function storeTranscript(transcript: string): string {
  const key = process.env.TWINMIND_ENCRYPTION_KEY!;
  return encrypt(transcript, key);
}

export function retrieveTranscript(encryptedTranscript: string): string {
  const key = process.env.TWINMIND_ENCRYPTION_KEY!;
  return decrypt(encryptedTranscript, key);
}

Step 5: Implement Access Control

// src/twinmind/auth/permissions.ts
export enum Permission {
  READ_TRANSCRIPTS = 'transcripts:read',
  WRITE_TRANSCRIPTS = 'transcripts:write',
  DELETE_TRANSCRIPTS = 'transcripts:delete',
  MANAGE_SETTINGS = 'settings:manage',
  VIEW_ANALYTICS = 'analytics:view',
  ADMIN = 'admin:*',
}

export interface User {
  id: string;
  email: string;
  permissions: Permission[];
  organizationId: string;
}

export function hasPermission(user: User, permission: Permission): boolean {
  if (user.permissions.includes(Permission.ADMIN)) {
    return true;
  }
  return user.permissions.includes(permission);
}

export function requirePermission(permission: Permission) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user as User;

    if (!user) {
      return res.status(401).json({ error: 'Unauthorized' });
    }

    if (!hasPermission(user, permission)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }

    next();
  };
}

// Usage in routes
app.get(
  '/api/transcripts',
  requirePermission(Permission.READ_TRANSCRIPTS),
  getTranscripts
);

app.delete(
  '/api/transcripts/:id',
  requirePermission(Permission.DELETE_TRANSCRIPTS),
  deleteTranscript
);

Step 6: Configure Privacy Settings

// src/twinmind/privacy.ts
export interface PrivacyConfig {
  // Audio handling
  storeAudio: boolean;
  audioRetentionDays: number;

  // Transcript handling
  storeTranscripts: boolean;
  transcriptRetentionDays: number;
  encryptTranscripts: boolean;

  // Processing
  processLocally: boolean; // Use on-device processing when possible

  // Sharing
  allowSharing: boolean;
  requireConsent: boolean;

  // PII handling
  redactPII: boolean;
  piiPatterns: string[];
}

const defaultPrivacyConfig: PrivacyConfig = {
  storeAudio: false, // TwinMind default - never store audio
  audioRetentionDays: 0,
  storeTranscripts: true,
  transcriptRetentionDays: 90,
  encryptTranscripts: true,
  processLocally: true,
  allowSharing: false,
  requireConsent: true,
  redactPII: true,
  piiPatterns: [
    '\\b\\d{3}-\\d{2}-\\d{4}\\b', // SSN
    '\\b\\d{16}\\b', // Credit card
    '\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b', // Email
  ],
};

export function redactPII(text: string, patterns: string[]): string {
  let redacted = text;

  for (const pattern of patterns) {
    const regex = new RegExp(pattern, 'gi');
    redacted = redacted.replace(regex, '[REDACTED]');
  }

  return redacted;
}

Step 7: Audit Logging

// src/twinmind/audit.ts
export interface AuditEvent {
  timestamp: Date;
  userId: string;
  action: string;
  resource: string;
  resourceId?: string;
  details?: Record<string, any>;
  ipAddress?: string;
  userAgent?: string;
}

export class AuditLogger {
  private events: AuditEvent[] = [];

  log(event: Omit<AuditEvent, 'timestamp'>): void {
    const fullEvent: AuditEvent = {
      ...event,
      timestamp: new Date(),
    };

    this.events.push(fullEvent);
    this.persist(fullEvent);

    // Log to console in development
    if (process.env.NODE_ENV === 'development') {
      console.log('[AUDIT]', JSON.stringify(fullEvent));
    }
  }

  private async persist(event: AuditEvent): Promise<void> {
    // Send to logging service (e.g., CloudWatch, Datadog)
    // await logService.write(event);
  }

  async query(filters: Partial<AuditEvent>): Promise<AuditEvent[]> {
    return this.events.filter(event => {
      return Object.entries(filters).every(([key, value]) =>
        event[key as keyof AuditEvent] === value
      );
    });
  }
}

export const auditLogger = new AuditLogger();

// Usage
auditLogger.log({
  userId: 'user_123',
  action: 'TRANSCRIPT_ACCESSED',
  resource: 'transcript',
  resourceId: 'tr_abc123',
  details: { method: 'GET', endpoint: '/api/transcripts/tr_abc123' },
});

Output

• Secure API key storage
• Webhook signature verification
• Data encryption at rest
• Access control implementation
• Privacy configuration
• Audit logging

Security Checklist

## Pre-Deployment Security Checklist

### API Security
- [ ] API keys stored in environment variables or secrets manager
- [ ] No hardcoded credentials in source code
- [ ] API key rotation process documented
- [ ] Rate limiting implemented

### Data Protection
- [ ] Transcripts encrypted at rest
- [ ] PII redaction enabled
- [ ] Data retention policies configured
- [ ] Backup encryption verified

### Authentication
- [ ] Webhook signatures verified
- [ ] JWT tokens validated properly
- [ ] Session timeout configured
- [ ] MFA enabled for admin accounts

### Access Control
- [ ] RBAC implemented
- [ ] Least privilege principle applied
- [ ] Regular permission audits scheduled

### Monitoring
- [ ] Audit logging enabled
- [ ] Failed auth attempts monitored
- [ ] Anomaly detection configured
- [ ] Incident response plan documented

Error Handling

TwinMind Privacy Features

TwinMind provides built-in privacy protection:

• No audio storage: Audio is processed in real-time and immediately deleted
• On-device processing: Transcription can run locally on device
• Encrypted backups: Optional cloud backups are encrypted
• Data residency: Choose data storage region (Enterprise)
• GDPR compliance: Data export and deletion support

Resources

• TwinMind Security Whitepaper
• TwinMind Privacy Policy
• OWASP Security Guidelines

Next Steps

For production deployment, see twinmind-prod-checklist.