Week 4 Review & Best Practices

📋Learning Objectives

• Recap all Week 4 integration topics
• Implement telemetry with sdk.telemetry
• Apply security best practices
• Complete the Week 4 assessment
• Preview Week 5 advanced topics

🔄Week 4 Recap

📊Telemetry & Observability

Production plugins need observability. The SDK provides sdk.telemetry for structured logging, metrics, and tracing.

Using sdk.telemetry

// src/utils/telemetry.ts
const sdk = (globalThis as any).pluginSdk;

// Structured logging
export function logInfo(message: string, data?: Record<string, any>) {
  sdk.telemetry.log('info', message, {
    plugin: 'role-viewer',
    ...data
  });
}

export function logError(message: string, error: Error, data?: Record<string, any>) {
  sdk.telemetry.log('error', message, {
    plugin: 'role-viewer',
    error: error.message,
    stack: error.stack,
    ...data
  });
}

// Track user actions
export function trackEvent(event: string, properties?: Record<string, any>) {
  sdk.telemetry.track(event, {
    plugin: 'role-viewer',
    timestamp: new Date().toISOString(),
    ...properties
  });
}

// Measure performance
export function measureTiming(name: string, durationMs: number) {
  sdk.telemetry.timing(name, durationMs, {
    plugin: 'role-viewer'
  });
}

Usage in Components

// Track API call timing
const fetchRoles = async () => {
  const startTime = performance.now();
  
  try {
    logInfo('Fetching user roles');
    
    const response = await sdk.api.fetch('/api/membership/users/me/roles');
    const data = await response.json();
    
    const duration = performance.now() - startTime;
    measureTiming('fetch_roles', duration);
    
    trackEvent('roles_loaded', { 
      count: data.roles?.length || 0,
      duration_ms: Math.round(duration)
    });
    
    return data;
  } catch (err: any) {
    logError('Failed to fetch roles', err);
    trackEvent('roles_load_error', { error: err.message });
    throw err;
  }
};

// Track user interactions
const handleRoleClick = (roleId: string) => {
  trackEvent('role_clicked', { role_id: roleId });
  navigateToDetail(roleId);
};

🔒Security Best Practices

1. Always Use sdk.api.fetch()

Never use raw fetch() for API calls. The SDK handles CSRF, session cookies, and error normalization.

// ❌ Wrong - missing CSRF, session cookie issues
const response = await fetch('/api/crud/workflows/run', {
  method: 'POST',
  body: JSON.stringify(data)
});

// ✅ Correct - SDK handles security automatically
const response = await sdk.api.fetch('/api/crud/workflows/run', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data)
});

2. Validate All User Input

// Use zod for runtime validation
import { z } from 'zod';

const AccessRequestSchema = z.object({
  resourceId: z.string().uuid(),
  justification: z.string().min(20).max(1000),
  duration: z.enum(['24h', '7d', '30d', 'permanent'])
});

const handleSubmit = (formData: unknown) => {
  // Throws if invalid
  const validated = AccessRequestSchema.parse(formData);
  
  // Safe to use
  return sdk.crud.run('access-request', validated);
};

3. Fail Closed on Auth Errors

// Authorization check with fail-closed pattern
const canPerformAction = async (resource: string, action: string): Promise<boolean> => {
  try {
    const result = await sdk.authz.evaluate({
      resource: { type: resource },
      action: { name: action }
    });
    return result.decision === true;
  } catch (err) {
    logError('Auth check failed', err as Error);
    // Fail closed - deny on error
    return false;
  }
};

4. Sanitize User-Generated Content

// Never render untrusted HTML directly

// ❌ XSS vulnerability
<div dangerouslySetInnerHTML={{ __html: userComment }} />

// ✅ Use text content (auto-escaped)
<div>{userComment}</div>

// ✅ Or sanitize if HTML is required
import DOMPurify from 'dompurify';
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userComment) }} />

5. Protect Secrets

// ❌ Never hardcode secrets
const API_KEY = 'sk-abc123secret';

// ❌ Never log tokens/secrets
console.log('Token:', accessToken);

// ✅ Secrets should only be in backend environment variables
// Plugins get tokens through secure httpOnly cookies managed by BFF

Security Checklist

🚀Production Deployment Checklist

• Build: Production bundle passes without errors
• Integrity: SHA-256 hash updated in plugins.yaml
• Permissions: All required API endpoints in permissions.api
• PDP Application: pdp_application matches policy configuration
• Telemetry: Logging and event tracking implemented
• Error handling: All API calls have proper error handlers
• Loading states: Skeleton UI for async operations
• Empty states: Meaningful UI when no data
• Authorization: All sensitive actions gated with PDP checks
• Documentation: README with setup and usage instructions

❓Knowledge Check

const result = await sdk.crud.run('workflow-name', {
  input_field: 'value'
});
console.log(result.workflow_run_id);

const results = await sdk.authz.batchEvaluate([
  { resource: { type: 'doc', id: '1' }, action: { name: 'edit' } },
  { resource: { type: 'doc', id: '2' }, action: { name: 'edit' } },
  // ... more
]);
// 1 API call instead of 10!

🔮Week 5 Preview: Advanced Topics

Week 5 covers advanced platform capabilities:

📝Day 20 Checkpoint

• Reviewed all Week 4 integration topics
• Implemented telemetry with sdk.telemetry
• Applied security best practices
• Completed Week 4 assessment
• Ready for Week 5 advanced topics