DEV Community: meta-closure

The Future of AI-Assisted Development: Production-Ready Contract Templates

meta-closure — Tue, 12 Aug 2025 13:20:23 +0000

Part 5 of 5: Deploying bulletproof systems and building AI-friendly template libraries

Welcome to the final part of our series! We've built a complete contract programming system. Now let's make it production-ready and create AI-friendly templates that make secure code the default choice for any AI tool.

🚀 Production Deployment Strategy

Environment-Specific Error Handling

// lib/contracts/production.ts

class ProductionErrorHandler {
  static handleContractViolation(error: ContractViolationError): any {
    // Always log security events
    this.logSecurityEvent(error);

    // Environment-specific responses
    if (process.env.NODE_ENV === 'production') {
      return this.getProductionResponse(error);
    } else {
      return this.getDevelopmentResponse(error);
    }
  }

  private static getProductionResponse(error: ContractViolationError): any {
    switch (error.layer) {
      case 'presentation':
        return { 
          redirect: '/login', 
          error: 'Authentication required' 
        };
      case 'action':
        return { 
          success: false, 
          error: this.getSafeErrorMessage(error.originalError)
        };
      case 'business':
        return { 
          success: false, 
          error: 'Access denied' 
        };
      case 'data':
        return { 
          success: false, 
          error: 'Operation failed' 
        };
      default:
        return { 
          success: false, 
          error: 'Request failed' 
        };
    }
  }

  private static getDevelopmentResponse(error: ContractViolationError): any {
    return {
      success: false,
      error: error.originalError?.message || 'Contract violation',
      debug: {
        contract: error.contractName,
        layer: error.layer,
        type: error.originalError?.type,
        stack: error.originalError?.stack
      }
    };
  }

  private static getSafeErrorMessage(error: any): string {
    const safeErrors = [
      'VALIDATION_FAILED',
      'RATE_LIMIT_EXCEEDED', 
      'AUTHENTICATION_REQUIRED',
      'SESSION_EXPIRED'
    ];

    if (error instanceof ContractError && safeErrors.includes(error.type)) {
      return error.message;
    }

    return 'Invalid request';
  }

  private static logSecurityEvent(error: ContractViolationError) {
    const logLevel = this.getLogLevel(error);
    const logData = {
      timestamp: new Date().toISOString(),
      type: 'contract_violation',
      severity: logLevel,
      contract: error.contractName,
      layer: error.layer,
      error_type: error.originalError?.type,
      // Redact sensitive data in production
      ...(process.env.NODE_ENV !== 'production' && {
        error_details: error.originalError?.message,
        stack: error.originalError?.stack
      })
    };

    switch (logLevel) {
      case 'critical':
        console.error('🚨 SECURITY ALERT:', logData);
        // In production, send to security monitoring system
        // sendToSecurityMonitoring(logData);
        break;
      case 'warning':
        console.warn('⚠️  Security Warning:', logData);
        break;
      default:
        console.log('ℹ️  Security Event:', logData);
    }
  }

  private static getLogLevel(error: ContractViolationError): 'info' | 'warning' | 'critical' {
    const criticalErrors = ['OWNERSHIP_DENIED', 'INSUFFICIENT_ROLE'];
    const warningErrors = ['RATE_LIMIT_EXCEEDED', 'BUSINESS_RULE_VIOLATION'];

    if (criticalErrors.includes(error.originalError?.type)) {
      return 'critical';
    } else if (warningErrors.includes(error.originalError?.type)) {
      return 'warning';
    }

    return 'info';
  }
}

// Global error handler integration
if (typeof window === 'undefined') { // Server-side only
  process.on('unhandledRejection', (reason, promise) => {
    if (reason instanceof ContractViolationError) {
      ProductionErrorHandler.handleContractViolation(reason);
    }
  });
}

Performance Monitoring and Optimization

// lib/contracts/monitoring.ts

interface ContractMetrics {
  executions: number;
  totalTime: number;
  failures: number;
  avgTime: number;
  p95Time: number;
  lastFailure?: Date;
}

class ContractPerformanceMonitor {
  private static metrics = new Map<string, ContractMetrics>();
  private static executionTimes = new Map<string, number[]>();

  static measureContract<T>(
    contractName: string,
    fn: () => Promise<T> | T
  ): Promise<T> | T {
    const start = performance.now();

    const updateMetrics = (success: boolean) => {
      const duration = performance.now() - start;

      // Update execution times for percentile calculation
      const times = this.executionTimes.get(contractName) || [];
      times.push(duration);

      // Keep only last 1000 measurements
      if (times.length > 1000) {
        times.shift();
      }
      this.executionTimes.set(contractName, times);

      // Update metrics
      const current = this.metrics.get(contractName) || {
        executions: 0,
        totalTime: 0,
        failures: 0,
        avgTime: 0,
        p95Time: 0
      };

      current.executions++;
      current.totalTime += duration;
      if (!success) {
        current.failures++;
        current.lastFailure = new Date();
      }
      current.avgTime = current.totalTime / current.executions;
      current.p95Time = this.calculateP95(times);

      this.metrics.set(contractName, current);

      // Alert on performance degradation
      if (duration > 1000) { // > 1 second
        console.warn(`⚠️  Slow contract execution: ${contractName} took ${duration.toFixed(2)}ms`);
      }
    };

    try {
      const result = fn();

      if (result instanceof Promise) {
        return result
          .then(res => {
            updateMetrics(true);
            return res;
          })
          .catch(err => {
            updateMetrics(false);
            throw err;
          });
      }

      updateMetrics(true);
      return result;
    } catch (error) {
      updateMetrics(false);
      throw error;
    }
  }

  private static calculateP95(times: number[]): number {
    if (times.length === 0) return 0;

    const sorted = [...times].sort((a, b) => a - b);
    const index = Math.ceil(sorted.length * 0.95) - 1;
    return sorted[index] || 0;
  }

  static getPerformanceReport(): {
    summary: {
      totalContracts: number;
      totalExecutions: number;
      overallFailureRate: string;
      slowestContracts: Array<{ name: string; avgTime: number; p95Time: number }>;
    };
    details: Array<{
      contract: string;
      executions: number;
      avgTimeMs: number;
      p95TimeMs: number;
      failureRate: string;
      lastFailure?: string;
    }>;
  } {
    const entries = Array.from(this.metrics.entries());
    const totalExecutions = entries.reduce((sum, [, stats]) => sum + stats.executions, 0);
    const totalFailures = entries.reduce((sum, [, stats]) => sum + stats.failures, 0);

    const details = entries
      .map(([name, stats]) => ({
        contract: name,
        executions: stats.executions,
        avgTimeMs: parseFloat(stats.avgTime.toFixed(2)),
        p95TimeMs: parseFloat(stats.p95Time.toFixed(2)),
        failureRate: `${((stats.failures / stats.executions) * 100).toFixed(1)}%`,
        ...(stats.lastFailure && { 
          lastFailure: stats.lastFailure.toISOString() 
        })
      }))
      .sort((a, b) => b.avgTimeMs - a.avgTimeMs);

    const slowestContracts = details
      .slice(0, 5)
      .map(d => ({ 
        name: d.contract, 
        avgTime: d.avgTimeMs, 
        p95Time: d.p95TimeMs 
      }));

    return {
      summary: {
        totalContracts: entries.length,
        totalExecutions,
        overallFailureRate: `${((totalFailures / totalExecutions) * 100).toFixed(1)}%`,
        slowestContracts
      },
      details
    };
  }

  // Health check endpoint
  static getHealthStatus(): { status: 'healthy' | 'warning' | 'critical'; issues: string[] } {
    const issues: string[] = [];
    let status: 'healthy' | 'warning' | 'critical' = 'healthy';

    this.metrics.forEach((stats, contractName) => {
      const failureRate = stats.failures / stats.executions;

      if (failureRate > 0.1) { // > 10% failure rate
        issues.push(`High failure rate in ${contractName}: ${(failureRate * 100).toFixed(1)}%`);
        status = 'critical';
      } else if (failureRate > 0.05) { // > 5% failure rate
        issues.push(`Elevated failure rate in ${contractName}: ${(failureRate * 100).toFixed(1)}%`);
        if (status === 'healthy') status = 'warning';
      }

      if (stats.p95Time > 500) { // > 500ms p95
        issues.push(`Slow performance in ${contractName}: ${stats.p95Time.toFixed(2)}ms p95`);
        if (status === 'healthy') status = 'warning';
      }
    });

    return { status, issues };
  }
}

// Enhanced contract decorator with monitoring
export function monitoredContract(options: ContractOptions) {
  return function(target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    const contractName = `${target.constructor.name}.${propertyName}`;

    descriptor.value = async function(...args: any[]) {
      return ContractPerformanceMonitor.measureContract(contractName, async () => {
        // Apply contract logic here
        const [input, context] = args;

        try {
          // Pre-conditions
          let validatedInput = input;
          for (const condition of options.requires || []) {
            if (typeof condition === 'function' && condition.length === 1) {
              validatedInput = condition(validatedInput);
            } else {
              await condition(validatedInput, context);
            }
          }

          // Execute original method
          const result = await originalMethod.call(this, validatedInput, context);

          // Post-conditions
          for (const condition of options.ensures || []) {
            await condition(result, validatedInput, context);
          }

          // Invariants
          for (const invariant of options.invariants || []) {
            if (!invariant(validatedInput, result)) {
              throw new ContractError('INVARIANT_VIOLATION', 
                `Invariant failed in ${contractName}`);
            }
          }

          return result;

        } catch (error) {
          throw new ContractViolationError(contractName, options.layer || 'unknown', error);
        }
      });
    };

    return descriptor;
  };
}

🤖 AI-Friendly Template Library

Complete Template System

// lib/contracts/ai-templates.ts

interface AIContractTemplate {
  name: string;
  description: string;
  pattern: string;
  contract: ContractOptions;
  example: string;
}

export class AIContractLibrary {
  private static templates: Map<string, AIContractTemplate> = new Map();

  static registerTemplate(template: AIContractTemplate) {
    this.templates.set(template.name, template);
  }

  static getTemplate(name: string): AIContractTemplate | undefined {
    return this.templates.get(name);
  }

  static getAllTemplates(): AIContractTemplate[] {
    return Array.from(this.templates.values());
  }

  static findTemplateByPattern(description: string): AIContractTemplate | undefined {
    const normalizedDesc = description.toLowerCase();

    return Array.from(this.templates.values()).find(template => 
      template.pattern.split('|').some(pattern => 
        normalizedDesc.includes(pattern.toLowerCase())
      )
    );
  }

  // AI Helper: Generate contract based on natural language
  static generateContractFromDescription(description: string): ContractOptions {
    const template = this.findTemplateByPattern(description);

    if (template) {
      return template.contract;
    }

    // Fallback: Basic contract generation
    return this.generateBasicContract(description);
  }

  private static generateBasicContract(description: string): ContractOptions {
    const desc = description.toLowerCase();
    const contract: ContractOptions = {
      requires: [],
      ensures: [],
      layer: 'action'
    };

    // Detect operation type
    if (desc.includes('create') || desc.includes('add') || desc.includes('new')) {
      contract.requires!.push(auth('user'), validates(z.any()));
      contract.ensures!.push(auditLog('creation'), returns(z.any()));
    } else if (desc.includes('update') || desc.includes('edit') || desc.includes('modify')) {
      contract.requires!.push(auth('user'), owns('id'), validates(z.any()));
      contract.ensures!.push(auditLog('update'), returns(z.any()));
    } else if (desc.includes('delete') || desc.includes('remove')) {
      contract.requires!.push(auth('user'), owns('id'));
      contract.ensures!.push(auditLog('deletion'));
    } else if (desc.includes('admin')) {
      contract.requires!.push(auth('admin'));
      contract.ensures!.push(auditLog('admin_action'));
    }

    // Detect rate limiting needs
    if (desc.includes('rate limit') || desc.includes('throttle')) {
      contract.requires!.push(rateLimit('operation', 10));
    }

    return contract;
  }
}

// Pre-defined templates for common patterns
const commonTemplates: AIContractTemplate[] = [
  {
    name: 'user_profile_update',
    description: 'Update user profile information',
    pattern: 'update profile|edit profile|change profile|profile update|update user',
    contract: {
      requires: [
        auth('user'),
        validates(userUpdateSchema),
        owns('userId'),
        rateLimit('updateProfile', 5)
      ],
      ensures: [
        returns(userOutputSchema),
        auditLog('profile_update')
      ],
      layer: 'action'
    },
    example: `
@contract(AIContractLibrary.getTemplate('user_profile_update').contract)
async updateUserProfile(input: UserUpdateInput, context: AuthContext): Promise<User> {
  return userService.updateUser(input, context);
}`
  },

  {
    name: 'admin_user_creation',
    description: 'Admin creates new user account',
    pattern: 'create user|add user|new user|admin create|user creation',
    contract: {
      requires: [
        auth('admin'),
        validates(userCreateSchema),
        rateLimit('createUser', 10),
        businessRule('Email must be unique', async (input) => {
          const existing = await userRepository.findByEmail(input.email);
          return !existing;
        })
      ],
      ensures: [
        returns(userOutputSchema),
        auditLog('user_creation')
      ],
      layer: 'action'
    },
    example: `
@contract(AIContractLibrary.getTemplate('admin_user_creation').contract)
async createUser(input: UserCreateInput, context: AuthContext): Promise<User> {
  return userService.createUser(input, context);
}`
  },

  {
    name: 'secure_data_access',
    description: 'Access sensitive data with full security',
    pattern: 'get data|fetch data|read data|access data|retrieve data',
    contract: {
      requires: [
        auth('user'),
        owns('resourceId'),
        rateLimit('dataAccess', 20)
      ],
      ensures: [
        auditLog('data_access'),
        returns(z.any())
      ],
      layer: 'business'
    },
    example: `
@contract(AIContractLibrary.getTemplate('secure_data_access').contract)
async getUserData(input: { resourceId: string }, context: AuthContext): Promise<any> {
  return dataService.getSecureData(input.resourceId, context);
}`
  },

  {
    name: 'bulk_operation',
    description: 'Process multiple items with validation',
    pattern: 'bulk|batch|multiple|mass update|bulk create|batch process',
    contract: {
      requires: [
        auth('admin'),
        (input: any[]) => {
          if (!Array.isArray(input)) {
            throw new ContractError('INVALID_BULK_INPUT', 'Input must be an array');
          }
          if (input.length > 100) {
            throw new ContractError('BULK_TOO_LARGE', 'Maximum 100 items per batch');
          }
          return true;
        },
        rateLimit('bulkOperation', 5)
      ],
      ensures: [
        auditLog('bulk_operation')
      ],
      layer: 'action'
    },
    example: `
@contract(AIContractLibrary.getTemplate('bulk_operation').contract)
async bulkUpdateUsers(input: UserUpdateInput[], context: AuthContext): Promise<User[]> {
  return Promise.all(input.map(user => userService.updateUser(user, context)));
}`
  },

  {
    name: 'public_api_endpoint',
    description: 'Public API with rate limiting only',
    pattern: 'public api|public endpoint|no auth|anonymous|public access',
    contract: {
      requires: [
        validates(z.any()),
        rateLimit('publicAPI', 100)
      ],
      ensures: [
        auditLog('public_api_call'),
        returns(z.any())
      ],
      layer: 'action'
    },
    example: `
@contract(AIContractLibrary.getTemplate('public_api_endpoint').contract)
async getPublicData(input: PublicRequest): Promise<PublicResponse> {
  return publicService.getData(input);
}`
  },

  {
    name: 'sensitive_admin_action',
    description: 'High-privilege admin operation with extra security',
    pattern: 'admin delete|admin action|sensitive|critical|dangerous|super admin',
    contract: {
      requires: [
        auth('admin'),
        businessRule('Requires super admin for sensitive operations', (input, context) => {
          return context.user.roles.includes('super_admin') || 
                 context.user.roles.includes('admin');
        }),
        rateLimit('sensitiveAdminAction', 3)
      ],
      ensures: [
        auditLog('sensitive_admin_action')
      ],
      layer: 'action'
    },
    example: `
@contract(AIContractLibrary.getTemplate('sensitive_admin_action').contract)
async deleteAllUserData(input: { userId: string }, context: AuthContext): Promise<void> {
  return adminService.deleteAllUserData(input.userId, context);
}`
  }
];

// Register all templates
commonTemplates.forEach(template => {
  AIContractLibrary.registerTemplate(template);
});

AI Code Generation Helper

// lib/contracts/ai-codegen.ts

export class AICodeGenerator {
  // Generate complete function with contract
  static generateSecureFunction(options: {
    functionName: string;
    description: string;
    inputType: string;
    outputType: string;
    serviceName?: string;
    customLogic?: string;
  }): string {
    const contract = AIContractLibrary.generateContractFromDescription(options.description);
    const template = AIContractLibrary.findTemplateByPattern(options.description);

    return `
// Auto-generated secure function: ${options.description}
${template ? `// Using template: ${template.name}` : '// Using basic contract generation'}
@contract(${this.formatContract(contract)})
async ${options.functionName}(
  input: ${options.inputType},
  context: AuthContext
): Promise<${options.outputType}> {
  ${options.customLogic || this.generateDefaultLogic(options)}
}`.trim();
  }

  private static formatContract(contract: ContractOptions): string {
    const parts: string[] = [];

    if (contract.requires?.length) {
      parts.push(`requires: [${contract.requires.map(r => r.toString()).join(', ')}]`);
    }

    if (contract.ensures?.length) {
      parts.push(`ensures: [${contract.ensures.map(e => e.toString()).join(', ')}]`);
    }

    if (contract.layer) {
      parts.push(`layer: '${contract.layer}'`);
    }

    return `{\n  ${parts.join(',\n  ')}\n}`;
  }

  private static generateDefaultLogic(options: {
    serviceName?: string;
    functionName: string;
  }): string {
    const service = options.serviceName || 'service';
    const method = options.functionName.replace(/^(create|update|delete|get)/, '').toLowerCase();

    return `return ${service}.${options.functionName.replace(/^(create|update|delete|get)/, '$1')}${method}(input, context);`;
  }

  // Generate test cases
  static generateTestCases(functionName: string, contractOptions: ContractOptions): string {
    return `
describe('${functionName}', () => {
  let mockContext: AuthContext;

  beforeEach(() => {
    mockContext = {
      user: { id: 'user-123', email: 'test@example.com', roles: ['user'] },
      session: { id: 'session-123', expiresAt: new Date(Date.now() + 3600000) }
    };
  });

  it('should succeed with valid input and context', async () => {
    const validInput = {
      // TODO: Add valid input based on your schema
    };

    const result = await ${functionName}(validInput, mockContext);
    expect(result).toBeDefined();
  });

  ${this.generateAuthTests(contractOptions)}

  ${this.generateValidationTests(contractOptions)}

  ${this.generateOwnershipTests(contractOptions)}
});`.trim();
  }

  private static generateAuthTests(contract: ContractOptions): string {
    const hasAuth = contract.requires?.some(r => r.toString().includes('auth'));
    if (!hasAuth) return '';

    return `
  it('should fail without authentication', async () => {
    mockContext.user = null as any;

    await expect(${contract}(validInput, mockContext))
      .rejects
      .toThrow('Authentication required');
  });

  it('should fail with expired session', async () => {
    mockContext.session.expiresAt = new Date(Date.now() - 1000);

    await expect(${contract}(validInput, mockContext))
      .rejects
      .toThrow('Session has expired');
  });`;
  }

  private static generateValidationTests(contract: ContractOptions): string {
    const hasValidation = contract.requires?.some(r => r.toString().includes('validates'));
    if (!hasValidation) return '';

    return `
  it('should fail with invalid input', async () => {
    const invalidInput = {
      // TODO: Add invalid input that should fail validation
    };

    await expect(${contract}(invalidInput, mockContext))
      .rejects
      .toThrow('Input validation failed');
  });`;
  }

  private static generateOwnershipTests(contract: ContractOptions): string {
    const hasOwnership = contract.requires?.some(r => r.toString().includes('owns'));
    if (!hasOwnership) return '';

    return `
  it('should fail when accessing other user resources', async () => {
    const otherUserInput = {
      userId: 'other-user-id',
      // TODO: Add other user's resource ID
    };

    await expect(${contract}(otherUserInput, mockContext))
      .rejects
      .toThrow('does not own resource');
  });`;
  }
}

AI-Assisted Development Workflow

// lib/contracts/ai-workflow.ts

export class AIWorkflowHelper {
  // Analyze existing code and suggest contracts
  static analyzeFunction(functionCode: string): {
    suggestions: string[];
    securityRisks: string[];
    recommendedContract: ContractOptions;
  } {
    const suggestions: string[] = [];
    const securityRisks: string[] = [];
    const contract: ContractOptions = { requires: [], ensures: [] };

    // Analyze for common patterns
    if (functionCode.includes('update') && !functionCode.includes('@contract')) {
      securityRisks.push('Update function without contract protection');
      suggestions.push('Add authentication and ownership checks');
      contract.requires!.push(auth('user'), owns('id'));
    }

    if (functionCode.includes('db.') || functionCode.includes('prisma.')) {
      securityRisks.push('Direct database access without validation');
      suggestions.push('Add input validation and audit logging');
      contract.requires!.push(validates(z.any()));
      contract.ensures!.push(auditLog('database_operation'));
    }

    if (functionCode.includes('admin') && !functionCode.includes('auth')) {
      securityRisks.push('Admin function without authentication');
      suggestions.push('Add admin role requirement');
      contract.requires!.push(auth('admin'));
    }

    if (functionCode.includes('FormData') || functionCode.includes('req.body')) {
      securityRisks.push('Raw input processing without validation');
      suggestions.push('Add input validation schema');
    }

    return {
      suggestions,
      securityRisks,
      recommendedContract: contract
    };
  }

  // Generate migration guide for existing codebase
  static generateMigrationPlan(codebase: string[]): {
    priority: 'high' | 'medium' | 'low';
    files: string[];
    suggestedContracts: Array<{
      file: string;
      function: string;
      contract: ContractOptions;
      reason: string;
    }>;
  } {
    const highRiskFiles: string[] = [];
    const mediumRiskFiles: string[] = [];
    const lowRiskFiles: string[] = [];
    const suggestedContracts: Array<{
      file: string;
      function: string;
      contract: ContractOptions;
      reason: string;
    }> = [];

    codebase.forEach(file => {
      const analysis = this.analyzeFunction(file);

      if (analysis.securityRisks.length > 2) {
        highRiskFiles.push(file);
      } else if (analysis.securityRisks.length > 0) {
        mediumRiskFiles.push(file);
      } else {
        lowRiskFiles.push(file);
      }

      if (analysis.securityRisks.length > 0) {
        suggestedContracts.push({
          file,
          function: 'extractedFunction', // Would be parsed from code
          contract: analysis.recommendedContract,
          reason: analysis.securityRisks.join(', ')
        });
      }
    });

    const priority = highRiskFiles.length > 0 ? 'high' : 
                    mediumRiskFiles.length > 0 ? 'medium' : 'low';

    return {
      priority,
      files: [...highRiskFiles, ...mediumRiskFiles, ...lowRiskFiles],
      suggestedContracts
    };
  }

  // Generate documentation for AI tools
  static generateAIDocumentation(): string {
    const templates = AIContractLibrary.getAllTemplates();

    return `
# AI Contract Programming Guide

## Quick Reference for AI Tools

When generating code, always include appropriate contracts using these patterns:

### Common Patterns

${templates.map(template => `
#### ${template.name}
**Use when**: ${template.description}
**Keywords**: ${template.pattern}

\`\`\`typescript
${template.example}
\`\`\`
`).join('\n')}

### Smart Contract Generation

For any function, you can use:

\`\`\`typescript
// AI: Just describe what you want!
@contract(AIContractLibrary.generateContractFromDescription("your description here"))
async yourFunction(input: InputType, context: AuthContext): Promise<OutputType> {
  // Your implementation
}
\`\`\`

### Security Checklist

Before generating any function, ensure:
- [ ] Authentication requirements are clear
- [ ] Input validation is included  
- [ ] Ownership checks are appropriate
- [ ] Rate limiting is considered
- [ ] Audit logging is enabled
- [ ] Output validation is included

### Layer Guidelines

- **Presentation Layer**: Basic auth only (login status, session validity)
- **Action Layer**: Permissions, validation, rate limiting
- **Business Layer**: Ownership, business rules
- **Data Layer**: Final security checks, audit logging

## Error Handling

All contract violations are automatically handled:
- Development: Detailed error messages with debug info
- Production: Safe, user-friendly error messages
- Logging: All security events are automatically logged

## Performance

Contracts are optimized for production:
- Static checks cached at startup
- Dynamic checks only when necessary
- Metrics collection for monitoring
- Health checks included
`;
  }
}

📊 Production Monitoring Dashboard

// lib/contracts/dashboard.ts

export class ContractDashboard {
  // Generate health check endpoint for monitoring
  static createHealthCheckEndpoint() {
    return {
      '/api/health/contracts': async (req: any, res: any) => {
        const health = ContractPerformanceMonitor.getHealthStatus();
        const performance = ContractPerformanceMonitor.getPerformanceReport();

        res.status(health.status === 'critical' ? 503 : 200).json({
          status: health.status,
          timestamp: new Date().toISOString(),
          contracts: {
            total: performance.summary.totalContracts,
            executions: performance.summary.totalExecutions,
            failureRate: performance.summary.overallFailureRate
          },
          issues: health.issues,
          topSlowest: performance.summary.slowestContracts
        });
      }
    };
  }

  // Generate metrics for external monitoring (Prometheus, etc.)
  static generatePrometheusMetrics(): string {
    const performance = ContractPerformanceMonitor.getPerformanceReport();
    const metrics: string[] = [];

    // Contract execution counts
    performance.details.forEach(contract => {
      metrics.push(
        `contract_executions_total{contract="${contract.contract}"} ${contract.executions}`
      );
      metrics.push(
        `contract_duration_ms{contract="${contract.contract}",quantile="avg"} ${contract.avgTimeMs}`
      );
      metrics.push(
        `contract_duration_ms{contract="${contract.contract}",quantile="p95"} ${contract.p95TimeMs}`
      );
      metrics.push(
        `contract_failures_total{contract="${contract.contract}"} ${
          Math.round(contract.executions * parseFloat(contract.failureRate) / 100)
        }`
      );
    });

    // Overall metrics
    metrics.push(`contract_total_executions ${performance.summary.totalExecutions}`);
    metrics.push(`contract_overall_failure_rate ${parseFloat(performance.summary.overallFailureRate)}`);

    return metrics.join('\n');
  }

  // Real-time dashboard data
  static getDashboardData() {
    const performance = ContractPerformanceMonitor.getPerformanceReport();
    const health = ContractPerformanceMonitor.getHealthStatus();

    return {
      overview: {
        status: health.status,
        totalContracts: performance.summary.totalContracts,
        totalExecutions: performance.summary.totalExecutions,
        overallFailureRate: performance.summary.overallFailureRate,
        currentIssues: health.issues.length
      },
      contracts: performance.details.map(contract => ({
        name: contract.contract,
        executions: contract.executions,
        avgTime: contract.avgTimeMs,
        p95Time: contract.p95TimeMs,
        failureRate: contract.failureRate,
        status: this.getContractStatus(contract)
      })),
      alerts: health.issues.map(issue => ({
        type: issue.includes('failure') ? 'error' : 'warning',
        message: issue,
        timestamp: new Date().toISOString()
      }))
    };
  }

  private static getContractStatus(contract: any): 'healthy' | 'warning' | 'critical' {
    const failureRate = parseFloat(contract.failureRate);

    if (failureRate > 10 || contract.p95TimeMs > 1000) {
      return 'critical';
    } else if (failureRate > 5 || contract.p95TimeMs > 500) {
      return 'warning';
    }

    return 'healthy';
  }
}

🎯 The Future of AI-Assisted Development

What We've Achieved

Our contract programming system has transformed how AI tools contribute to codebases:

✅ Security by Default: AI can't generate insecure code anymore

✅ Guided Development: Templates guide AI toward best practices

✅ Production Ready: Full monitoring, error handling, and optimization

✅ Self-Documenting: Contracts serve as executable documentation

✅ Fail-Safe: Multiple layers catch what others miss

Real-World Impact

// Before: AI generates this dangerous code
async function updateUser(data: any) {
  return db.user.update({ where: { id: data.id }, data });
}

// After: AI generates this secure code automatically
@contract(AIContractLibrary.getTemplate('user_profile_update').contract)
async function updateUser(input: UserUpdateInput, context: AuthContext): Promise<User> {
  return userService.updateUser(input, context);
}

Deployment Checklist

// production-deployment-checklist.ts

export const ProductionChecklist = [
  // 1. Environment Setup
  'Set NODE_ENV=production',
  'Configure error logging service',
  'Set up performance monitoring',
  'Enable audit log storage',

  // 2. Security Configuration  
  'Review all contract templates',
  'Verify admin role requirements',
  'Test rate limiting configurations',
  'Validate session management',

  // 3. Monitoring Setup
  'Deploy health check endpoints',
  'Configure alerting thresholds',
  'Set up Prometheus metrics',
  'Test dashboard functionality',

  // 4. Testing
  'Run full contract test suite',
  'Verify error handling in production mode',
  'Test all security boundaries',
  'Load test with realistic traffic',

  // 5. Documentation
  'Generate AI development guide',
  'Document contract templates',
  'Create troubleshooting guide',
  'Train team on contract patterns'
];

🚀 Getting Started Today

Install the contracts system in your existing project
Choose 3-5 critical functions to secure first
Apply appropriate contract templates
Test thoroughly with the provided test helpers
Monitor and iterate using the dashboard
Expand gradually to cover your entire codebase

🎉 Series Conclusion

We've built something revolutionary: A development system that makes AI tools contribute securely by default. No more hoping AI gets security right – we've made insecure code impossible to deploy.

The Path Forward

This is just the beginning. As AI tools become more sophisticated, contract programming will evolve to:

Automatically generate business rules from natural language requirements
Adapt security policies based on threat intelligence
Optimize performance through intelligent contract compilation
Provide real-time security guidance during development

Your Turn

Try implementing contract programming in your next project. Start small, secure the critical paths first, and watch as your AI-generated code becomes bulletproof.

Questions? Success stories? Want to contribute templates?

Drop them in the comments! Let's build the future of secure AI-assisted development together.

Thank you for following this journey. Here's to a future where AI and humans collaborate safely and effectively!

📚 Series Navigation

Advanced Contract Patterns and Testing Strategies for AI-Safe Development

meta-closure — Tue, 12 Aug 2025 13:19:21 +0000

Part 4 of 5: Mastering complex business rules, contract composition, and bulletproof testing

Welcome back! In Part 3, we built a complete Next.js user management system. Today, we're diving deep into advanced contract patterns that handle the most complex business scenarios and ensure your AI-generated code remains bulletproof.

🧩 Contract Composition and Inheritance

Real applications need flexible, reusable contracts. Let's build a system that can handle complex combinations:

Base Contract Templates

// lib/contracts/templates.ts

// Common contract building blocks
export const baseUserContract = {
  requires: [auth('user')],
  ensures: [auditLog('user_operation')]
};

export const adminUserContract = {
  requires: [auth('admin'), rateLimit('admin_operation', 20)],
  ensures: [auditLog('admin_operation')]
};

export const ownershipContract = (resourceField: string) => ({
  requires: [owns(resourceField)],
  ensures: [auditLog(`${resourceField}_access`)]
});

// Contract composition function
export function composeContracts(...contracts: Partial<ContractOptions>[]): ContractOptions {
  return {
    requires: contracts.flatMap(c => c.requires || []),
    ensures: contracts.flatMap(c => c.ensures || []),
    invariants: contracts.flatMap(c => c.invariants || []),
    layer: contracts.find(c => c.layer)?.layer
  };
}

// Pre-built contract combinations
export const ContractTemplates = {
  // Standard CRUD operations
  userCRUD: (requiredRole: string = 'user') => composeContracts(
    baseUserContract,
    {
      requires: [validates(userUpdateSchema), owns('userId')],
      ensures: [returns(userOutputSchema)]
    }
  ),

  // Admin-only operations  
  adminOnly: (operation: string) => composeContracts(
    adminUserContract,
    {
      requires: [validates(z.any())],
      ensures: [returns(z.any())]
    }
  ),

  // Public API (no auth required)
  publicAPI: (operation: string, schema: z.ZodSchema) => ({
    requires: [validates(schema), rateLimit(`public_${operation}`, 100)],
    ensures: [auditLog(`public_${operation}`)]
  }),

  // Bulk operations
  bulkOperation: (itemContract: ContractOptions) => ({
    requires: [
      auth('admin'),
      (input: any[]) => {
        if (!Array.isArray(input)) {
          throw new ContractError('INVALID_BULK_INPUT', 'Input must be an array');
        }
        if (input.length > 1000) {
          throw new ContractError('BATCH_TOO_LARGE', 'Batch size must be ≤ 1000 items');
        }
        return true;
      }
    ],
    ensures: [auditLog('batch_operation')]
  })
};

Using Contract Composition

// lib/services/posts.ts
class PostService {
  // Combining multiple contract concerns
  @contract(composeContracts(
    baseUserContract,
    ownershipContract('postId'),
    {
      requires: [validates(postUpdateSchema)],
      ensures: [returns(postOutputSchema)],
      invariants: [(input, output) => output.id === input.postId]
    }
  ))
  async updatePost(input: PostUpdateInput, context: AuthContext): Promise<Post> {
    // Implementation
  }

  // Using pre-built templates
  @contract(ContractTemplates.adminOnly('deleteAnyPost'))
  async adminDeletePost(input: { postId: string }, context: AuthContext): Promise<void> {
    // Implementation
  }
}

🔀 Conditional Contracts

Sometimes contracts need to adapt based on context. Here's how to build dynamic contracts:

// lib/contracts/conditional.ts

export function conditionalContract(
  condition: (input: any, context: any) => boolean,
  whenTrue: ContractOptions,
  whenFalse: ContractOptions = {}
): MethodDecorator {
  return function(target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;

    descriptor.value = async function(...args: any[]) {
      const [input, context] = args;
      const contractToApply = condition(input, context) ? whenTrue : whenFalse;

      // Apply the selected contract
      const contractDecorator = contract(contractToApply);
      const tempDescriptor = { value: originalMethod };
      contractDecorator(target, propertyName, tempDescriptor);

      return tempDescriptor.value.apply(this, args);
    };

    return descriptor;
  };
}

// Usage examples
class UserService {
  // Different contracts based on role change
  @conditionalContract(
    (input, context) => input.role && input.role !== context.user.roles[0],
    // Role change requires admin privileges
    { 
      requires: [auth('admin'), businessRule('Role change requires admin', () => true)],
      ensures: [auditLog('role_change')]
    },
    // Normal profile update
    { 
      requires: [auth('user'), owns('userId')],
      ensures: [auditLog('profile_update')]
    }
  )
  async updateUser(input: UserUpdateInput, context: AuthContext): Promise<User> {
    // Implementation adapts automatically
  }

  // Time-based contracts
  @conditionalContract(
    (input, context) => {
      const hour = new Date().getHours();
      return hour >= 9 && hour <= 17; // Business hours
    },
    // Business hours: normal rate limit
    { requires: [rateLimit('createUser', 10)] },
    // Off hours: stricter rate limit
    { requires: [rateLimit('createUser', 3)] }
  )
  async createUser(input: UserCreateInput, context: AuthContext): Promise<User> {
    // Rate limiting adapts to time of day
  }
}

🔄 Bulk Operation Contracts

Handling arrays of data safely:

// lib/contracts/bulk.ts

export function bulkContract(itemContract: ContractOptions): ContractOptions {
  return {
    requires: [
      // Validate input is array
      (input: any[], context: AuthContext) => {
        if (!Array.isArray(input)) {
          throw new ContractError('INVALID_BULK_INPUT', 'Input must be an array');
        }
        if (input.length === 0) {
          throw new ContractError('EMPTY_BULK_INPUT', 'Input array cannot be empty');
        }
        if (input.length > 1000) {
          throw new ContractError('BULK_TOO_LARGE', 'Batch size must be ≤ 1000 items');
        }
        return true;
      },
      // Apply item-level requires to each item
      async (input: any[], context: AuthContext) => {
        for (let i = 0; i < input.length; i++) {
          try {
            for (const condition of itemContract.requires || []) {
              if (typeof condition === 'function' && condition.length === 1) {
                input[i] = condition(input[i]);
              } else {
                await condition(input[i], context);
              }
            }
          } catch (error) {
            throw new ContractError('BULK_ITEM_VALIDATION_FAILED', 
              `Item ${i} failed validation: ${error.message}`);
          }
        }
        return true;
      }
    ],
    ensures: [
      // Apply item-level ensures to each result
      async (output: any[], input: any[], context: AuthContext) => {
        for (let i = 0; i < output.length; i++) {
          for (const condition of itemContract.ensures || []) {
            await condition(output[i], input[i], context);
          }
        }
        return true;
      }
    ]
  };
}

// Usage
class UserService {
  @contract(bulkContract({
    requires: [owns('userId'), validates(userUpdateSchema)],
    ensures: [auditLog('bulk_user_update'), returns(userOutputSchema)]
  }))
  async bulkUpdateUsers(users: UserUpdateInput[], context: AuthContext): Promise<User[]> {
    const results = [];
    for (const user of users) {
      results.push(await this.updateUser(user, context));
    }
    return results;
  }
}

🔍 Advanced Debugging and Monitoring

Contract Execution Visualization

// lib/contracts/debug.ts

interface ContractExecution {
  contractName: string;
  layer: string;
  timestamp: Date;
  input: any;
  output?: any;
  status: 'success' | 'failure';
  error?: any;
  duration: number;
}

class ContractDebugger {
  private static executions: ContractExecution[] = [];
  private static isEnabled = process.env.NODE_ENV === 'development';

  static logExecution(
    contractName: string,
    layer: string,
    input: any,
    output?: any,
    error?: any,
    duration?: number
  ) {
    if (!this.isEnabled) return;

    const execution: ContractExecution = {
      contractName,
      layer,
      timestamp: new Date(),
      input: this.sanitizeForLog(input),
      output: this.sanitizeForLog(output),
      status: error ? 'failure' : 'success',
      error: error?.message,
      duration: duration || 0
    };

    this.executions.push(execution);

    // Real-time console output
    const icon = error ? '❌' : '✅';
    const timeStr = duration ? ` (${duration.toFixed(2)}ms)` : '';
    console.log(`${icon} Contract [${layer}] ${contractName}${timeStr}`, {
      input: execution.input,
      ...(output && { output: execution.output }),
      ...(error && { error: error.message })
    });

    // Keep only last 1000 executions
    if (this.executions.length > 1000) {
      this.executions = this.executions.slice(-1000);
    }
  }

  static getExecutionReport(): {
    summary: {
      total: number;
      success: number;
      failure: number;
      successRate: string;
      avgDuration: number;
    };
    byLayer: Record<string, { success: number; failure: number; avgDuration: number }>;
    recentFailures: ContractExecution[];
  } {
    const total = this.executions.length;
    const successes = this.executions.filter(e => e.status === 'success');
    const failures = this.executions.filter(e => e.status === 'failure');

    const avgDuration = this.executions.reduce((sum, e) => sum + e.duration, 0) / total;

    const byLayer = this.executions.reduce((acc, e) => {
      if (!acc[e.layer]) {
        acc[e.layer] = { success: 0, failure: 0, durations: [] };
      }
      acc[e.layer][e.status]++;
      acc[e.layer].durations.push(e.duration);
      return acc;
    }, {} as any);

    // Calculate averages
    Object.keys(byLayer).forEach(layer => {
      const durations = byLayer[layer].durations;
      byLayer[layer].avgDuration = durations.reduce((a, b) => a + b, 0) / durations.length;
      delete byLayer[layer].durations;
    });

    return {
      summary: {
        total,
        success: successes.length,
        failure: failures.length,
        successRate: `${((successes.length / total) * 100).toFixed(1)}%`,
        avgDuration: parseFloat(avgDuration.toFixed(2))
      },
      byLayer,
      recentFailures: failures.slice(-10)
    };
  }

  private static sanitizeForLog(data: any): any {
    if (typeof data !== 'object' || data === null) return data;

    const sanitized = { ...data };
    delete sanitized.password;
    delete sanitized.token;
    delete sanitized.secret;
    return sanitized;
  }
}

// Enhanced contract decorator with debugging
export function debuggableContract(options: ContractOptions) {
  return function(target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    const contractName = `${target.constructor.name}.${propertyName}`;

    descriptor.value = async function(...args: any[]) {
      const startTime = performance.now();
      const [input, context] = args;

      try {
        // Apply all contract conditions
        let validatedInput = input;
        for (const condition of options.requires || []) {
          if (typeof condition === 'function' && condition.length === 1) {
            validatedInput = condition(validatedInput);
          } else {
            await condition(validatedInput, context);
          }
        }

        const result = await originalMethod.call(this, validatedInput, context);

        for (const condition of options.ensures || []) {
          await condition(result, validatedInput, context);
        }

        for (const invariant of options.invariants || []) {
          if (!invariant(validatedInput, result)) {
            throw new ContractError('INVARIANT_VIOLATION', 
              `Invariant condition failed in ${contractName}`);
          }
        }

        const duration = performance.now() - startTime;
        ContractDebugger.logExecution(contractName, options.layer || 'unknown', input, result, null, duration);

        return result;

      } catch (error) {
        const duration = performance.now() - startTime;
        ContractDebugger.logExecution(contractName, options.layer || 'unknown', input, null, error, duration);

        throw new ContractViolationError(contractName, options.layer || 'unknown', error);
      }
    };

    return descriptor;
  };
}

// Make debugger available globally in development
if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
  (window as any).__contractDebugger = ContractDebugger;
}

🧪 Comprehensive Testing Strategies

Contract Unit Testing

// __tests__/contracts.test.ts
import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { auth, owns, validates, rateLimit } from '@/lib/contracts';
import { userUpdateSchema } from '@/lib/schemas/user';

describe('Contract Conditions', () => {
  let mockContext: AuthContext;

  beforeEach(() => {
    mockContext = {
      user: { id: 'user-123', email: 'test@example.com', roles: ['user'] },
      session: { id: 'session-123', expiresAt: new Date(Date.now() + 3600000) }
    };
  });

  describe('auth condition', () => {
    it('should pass with valid user and role', async () => {
      const authCondition = auth('user');
      await expect(authCondition({}, mockContext)).resolves.toBe(true);
    });

    it('should fail with insufficient role', async () => {
      const authCondition = auth('admin');
      await expect(authCondition({}, mockContext))
        .rejects
        .toThrow('Required role: admin');
    });

    it('should fail with expired session', async () => {
      mockContext.session.expiresAt = new Date(Date.now() - 1000);
      const authCondition = auth('user');
      await expect(authCondition({}, mockContext))
        .rejects
        .toThrow('Session has expired');
    });

    it('should fail with no user', async () => {
      mockContext.user = null as any;
      const authCondition = auth('user');
      await expect(authCondition({}, mockContext))
        .rejects
        .toThrow('User must be logged in');
    });
  });

  describe('owns condition', () => {
    beforeEach(() => {
      jest.spyOn(global, 'getResourceById').mockImplementation(async (id) => {
        const resources = {
          'resource-123': { id: 'resource-123', userId: 'user-123' },
          'resource-456': { id: 'resource-456', userId: 'user-456' }
        };
        return resources[id] || null;
      });
    });

    it('should pass for resource owner', async () => {
      const ownsCondition = owns('resourceId');
      await expect(ownsCondition({ resourceId: 'resource-123' }, mockContext))
        .resolves.toBe(true);
    });

    it('should pass for admin', async () => {
      mockContext.user.roles = ['admin'];
      const ownsCondition = owns('resourceId');
      await expect(ownsCondition({ resourceId: 'resource-456' }, mockContext))
        .resolves.toBe(true);
    });

    it('should fail for non-owner', async () => {
      const ownsCondition = owns('resourceId');
      await expect(ownsCondition({ resourceId: 'resource-456' }, mockContext))
        .rejects
        .toThrow('does not own resource');
    });

    it('should fail with missing resource ID', async () => {
      const ownsCondition = owns('resourceId');
      await expect(ownsCondition({}, mockContext))
        .rejects
        .toThrow('Field resourceId is required');
    });
  });

  describe('validates condition', () => {
    it('should pass with valid input', () => {
      const validatesCondition = validates(userUpdateSchema);
      const validInput = {
        userId: '123e4567-e89b-12d3-a456-426614174000',
        email: 'test@example.com',
        name: 'Test User'
      };

      expect(() => validatesCondition(validInput)).not.toThrow();
    });

    it('should fail with invalid email', () => {
      const validatesCondition = validates(userUpdateSchema);
      const invalidInput = {
        userId: '123e4567-e89b-12d3-a456-426614174000',
        email: 'invalid-email',
        name: 'Test User'
      };

      expect(() => validatesCondition(invalidInput))
        .toThrow('Input validation failed');
    });

    it('should fail with invalid UUID', () => {
      const validatesCondition = validates(userUpdateSchema);
      const invalidInput = {
        userId: 'not-a-uuid',
        email: 'test@example.com',
        name: 'Test User'
      };

      expect(() => validatesCondition(invalidInput))
        .toThrow('Invalid user ID format');
    });
  });

  describe('rateLimit condition', () => {
    beforeEach(() => {
      // Reset rate limit store
      jest.clearAllMocks();
    });

    it('should pass under rate limit', async () => {
      const rateLimitCondition = rateLimit('testOperation', 5);
      await expect(rateLimitCondition({}, mockContext)).resolves.toBe(true);
    });

    it('should fail when rate limit exceeded', async () => {
      const rateLimitCondition = rateLimit('testOperation', 1);

      // First call should succeed
      await expect(rateLimitCondition({}, mockContext)).resolves.toBe(true);

      // Second call should fail
      await expect(rateLimitCondition({}, mockContext))
        .rejects
        .toThrow('Rate limit exceeded');
    });
  });
});

Integration Testing with Contracts

// __tests__/user-service.integration.test.ts
import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
import { UserService } from '@/lib/services/users';
import { ContractViolationError } from '@/lib/contracts';
import { userRepository } from '@/lib/data/users';

describe('UserService Integration', () => {
  let userService: UserService;
  let mockContext: AuthContext;

  beforeEach(() => {
    userService = new UserService();
    mockContext = {
      user: { id: 'user-123', email: 'user@test.com', roles: ['user'] },
      session: { id: 'session-123', expiresAt: new Date(Date.now() + 3600000) }
    };

    // Mock repository methods
    jest.spyOn(userRepository, 'findById').mockResolvedValue({
      id: 'user-123',
      email: 'user@test.com',
      name: 'Test User',
      role: 'user',
      createdAt: new Date(),
      updatedAt: new Date()
    });

    jest.spyOn(userRepository, 'save').mockImplementation(async (user) => ({
      ...user,
      updatedAt: new Date()
    }));
  });

  afterEach(() => {
    jest.restoreAllMocks();
  });

  describe('updateUser', () => {
    it('should successfully update own profile', async () => {
      const input = {
        userId: 'user-123',
        email: 'newemail@test.com',
        name: 'New Name'
      };

      const result = await userService.updateUser(input, mockContext);

      expect(result.email).toBe('newemail@test.com');
      expect(result.name).toBe('New Name');
      expect(userRepository.save).toHaveBeenCalledWith(
        expect.objectContaining({
          email: 'newemail@test.com',
          name: 'New Name'
        }),
        mockContext
      );
    });

    it('should fail when trying to update other user profile', async () => {
      const input = {
        userId: 'user-456', // Different user
        email: 'newemail@test.com',
        name: 'New Name'
      };

      await expect(userService.updateUser(input, mockContext))
        .rejects
        .toThrow(ContractViolationError);
    });

    it('should prevent role change by non-admin', async () => {
      const input = {
        userId: 'user-123',
        role: 'admin' // Trying to escalate privileges
      };

      await expect(userService.updateUser(input, mockContext))
        .rejects
        .toThrow('Cannot change own role');
    });

    it('should allow admin to change roles', async () => {
      mockContext.user.roles = ['admin'];
      const input = {
        userId: 'user-123',
        role: 'moderator'
      };

      const result = await userService.updateUser(input, mockContext);
      expect(result.role).toBe('moderator');
    });

    it('should enforce email change frequency limit', async () => {
      // Mock user with recent email change
      jest.spyOn(userRepository, 'findById').mockResolvedValue({
        id: 'user-123',
        email: 'old@test.com',
        name: 'Test User',
        role: 'user',
        createdAt: new Date(),
        updatedAt: new Date(),
        emailChangedAt: new Date() // Changed today
      });

      const input = {
        userId: 'user-123',
        email: 'new@test.com'
      };

      await expect(userService.updateUser(input, mockContext))
        .rejects
        .toThrow('Email change frequency limit');
    });
  });

  describe('createUser', () => {
    beforeEach(() => {
      mockContext.user.roles = ['admin']; // Admin required for user creation
      jest.spyOn(userRepository, 'findByEmail').mockResolvedValue(null); // No duplicate
      jest.spyOn(userRepository, 'create').mockImplementation(async (user) => user);
    });

    it('should successfully create user as admin', async () => {
      const input = {
        email: 'newuser@test.com',
        name: 'New User',
        role: 'user' as const
      };

      const result = await userService.createUser(input, mockContext);

      expect(result.email).toBe('newuser@test.com');
      expect(result.name).toBe('New User');
      expect(result.role).toBe('user');
    });

    it('should fail when non-admin tries to create user', async () => {
      mockContext.user.roles = ['user'];

      const input = {
        email: 'newuser@test.com',
        name: 'New User',
        role: 'user' as const
      };

      await expect(userService.createUser(input, mockContext))
        .rejects
        .toThrow('Required role: admin');
    });

    it('should fail with duplicate email', async () => {
      jest.spyOn(userRepository, 'findByEmail').mockResolvedValue({
        id: 'existing-user',
        email: 'duplicate@test.com',
        name: 'Existing User',
        role: 'user',
        createdAt: new Date(),
        updatedAt: new Date()
      });

      const input = {
        email: 'duplicate@test.com',
        name: 'New User',
        role: 'user' as const
      };

      await expect(userService.createUser(input, mockContext))
        .rejects
        .toThrow('Email must be unique');
    });
  });
});

Contract Mock System

// __tests__/helpers/contract-mocker.ts

export class ContractMocker {
  private originalConditions = new Map<string, any>();
  private mocks = new Map<string, any>();

  mockCondition(conditionName: string, result: any) {
    this.mocks.set(conditionName, result);
  }

  mockAuth(result: boolean | Error) {
    this.mockCondition('auth', result);
  }

  mockOwnership(result: boolean | Error) {
    this.mockCondition('owns', result);
  }

  mockValidation(result: any | Error) {
    this.mockCondition('validates', result);
  }

  mockRateLimit(result: boolean | Error) {
    this.mockCondition('rateLimit', result);
  }

  applyMocks() {
    // Store originals
    this.originalConditions.set('auth', global.auth);
    this.originalConditions.set('owns', global.owns);
    this.originalConditions.set('validates', global.validates);
    this.originalConditions.set('rateLimit', global.rateLimit);

    // Apply mocks
    global.auth = () => async () => {
      const mock = this.mocks.get('auth');
      if (mock instanceof Error) throw mock;
      return mock ?? true;
    };

    global.owns = () => async () => {
      const mock = this.mocks.get('owns');
      if (mock instanceof Error) throw mock;
      return mock ?? true;
    };

    global.validates = () => (input: any) => {
      const mock = this.mocks.get('validates');
      if (mock instanceof Error) throw mock;
      return mock ?? input;
    };

    global.rateLimit = () => async () => {
      const mock = this.mocks.get('rateLimit');
      if (mock instanceof Error) throw mock;
      return mock ?? true;
    };

    return this.restoreMocks.bind(this);
  }

  restoreMocks() {
    // Restore originals
    this.originalConditions.forEach((original, name) => {
      (global as any)[name] = original;
    });

    this.originalConditions.clear();
    this.mocks.clear();
  }
}

// Usage in tests
describe('Contract Mocking', () => {
  let contractMocker: ContractMocker;
  let restoreMocks: () => void;

  beforeEach(() => {
    contractMocker = new ContractMocker();
    restoreMocks = contractMocker.applyMocks();
  });

  afterEach(() => {
    restoreMocks();
  });

  it('should handle auth failure gracefully', async () => {
    contractMocker.mockAuth(new ContractError('AUTH_FAILED', 'Mock auth failure'));

    await expect(userService.updateUser(validInput, mockContext))
      .rejects
      .toThrow('Mock auth failure');
  });

  it('should bypass rate limiting in tests', async () => {
    contractMocker.mockRateLimit(true);

    // Can now test business logic without rate limit interference
    const result = await userService.updateUser(validInput, mockContext);
    expect(result).toBeDefined();
  });
});

📊 Performance Optimization

Contract Compilation and Caching

// lib/contracts/performance.ts

interface CompiledContract {
  staticChecks: Function[];
  dynamicChecks: Function[];
  postConditions: Function[];
  invariants: Function[];
}

class ContractOptimizer {
  private static contractCache = new Map<string, CompiledContract>();
  private static conditionCache = new Map<string, any>();

  static compileContract(contractName: string, options: ContractOptions): CompiledContract {
    if (this.contractCache.has(contractName)) {
      return this.contractCache.get(contractName)!;
    }

    const compiled = this.optimizeContract(options);
    this.contractCache.set(contractName, compiled);

    return compiled;
  }

  private static optimizeContract(options: ContractOptions): CompiledContract {
    const requires = options.requires || [];

    return {
      staticChecks: this.extractStaticChecks(requires),
      dynamicChecks: this.extractDynamicChecks(requires),
      postConditions: options.ensures || [],
      invariants: options.invariants || []
    };
  }

  private static extractStaticChecks(conditions: any[]): Function[] {
    return conditions.filter(c => 
      typeof c === 'function' && 
      c.length === 1 && // Validators take only input
      !c.toString().includes('await') &&
      !c.toString().includes('async')
    );
  }

  private static extractDynamicChecks(conditions: any[]): Function[] {
    return conditions.filter(c => 
      typeof c === 'function' && (
        c.length === 2 || // Conditions take input + context
        c.toString().includes('await') ||
        c.toString().includes('async')
      )
    );
  }

  // Schema compilation and caching
  static getCachedValidator(schemaKey: string, schema: z.ZodSchema) {
    if (!this.conditionCache.has(schemaKey)) {
      const compiledValidator = schema.parse.bind(schema);
      this.conditionCache.set(schemaKey, compiledValidator);
    }

    return this.conditionCache.get(schemaKey);
  }

  static clearCache() {
    this.contractCache.clear();
    this.conditionCache.clear();
  }
}

// Optimized contract decorator
export function optimizedContract(options: ContractOptions) {
  return function(target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    const contractName = `${target.constructor.name}.${propertyName}`;
    const compiled = ContractOptimizer.compileContract(contractName, options);

    descriptor.value = async function(...args: any[]) {
      const [input, context] = args;

      try {
        // Static checks first (fastest)
        let validatedInput = input;
        for (const check of compiled.staticChecks) {
          validatedInput = check(validatedInput);
        }

        // Dynamic checks (slower, but necessary)
        for (const check of compiled.dynamicChecks) {
          await check(validatedInput, context);
        }

        // Execute original method
        const result = await originalMethod.call(this, validatedInput, context);

        // Post-conditions
        for (const condition of compiled.postConditions) {
          await condition(result, validatedInput, context);
        }

        // Invariants
        for (const invariant of compiled.invariants) {
          if (!invariant(validatedInput, result)) {
            throw new ContractError('INVARIANT_VIOLATION', 
              `Invariant failed in ${contractName}`);
          }
        }

        return result;

      } catch (error) {
        throw new ContractViolationError(contractName, options.layer || 'unknown', error);
      }
    };

    return descriptor;
  };
}

🎯 AI-Friendly Development Patterns

Smart Contract Generation

// lib/contracts/ai-helpers.ts

// AI can use this to auto-generate appropriate contracts
export function smartContract(options: {
  operation: 'create' | 'read' | 'update' | 'delete';
  resource: string;
  visibility: 'public' | 'private' | 'admin';
  rateLimit?: number;
  customRules?: string[];
}): ContractOptions {
  const contracts: ContractOptions = {
    requires: [],
    ensures: [],
    invariants: []
  };

  // Visibility-based auth requirements
  switch (options.visibility) {
    case 'public':
      // No auth required
      break;
    case 'private':
      contracts.requires!.push(auth('user'));
      if (options.operation !== 'create') {
        contracts.requires!.push(owns(`${options.resource}Id`));
      }
      break;
    case 'admin':
      contracts.requires!.push(auth('admin'));
      break;
  }

  // Operation-based validation
  if (['create', 'update'].includes(options.operation)) {
    contracts.requires!.push(
      validates(getSchemaForResource(options.resource, options.operation))
    );
  }

  // Rate limiting
  if (options.rateLimit) {
    contracts.requires!.push(
      rateLimit(`${options.operation}_${options.resource}`, options.rateLimit)
    );
  }

  // Always audit
  contracts.ensures!.push(
    auditLog(`${options.operation}_${options.resource}`)
  );

  // Output validation for data-returning operations
  if (['create', 'read', 'update'].includes(options.operation)) {
    contracts.ensures!.push(
      returns(getSchemaForResource(options.resource, 'output'))
    );
  }

  return contracts;
}

function getSchemaForResource(resource: string, operation: string): z.ZodSchema {
  const schemas: Record<string, Record<string, z.ZodSchema>> = {
    user: {
      create: userCreateSchema,
      update: userUpdateSchema,
      output: userOutputSchema
    },
    post: {
      create: postCreateSchema,
      update: postUpdateSchema,
      output: postOutputSchema
    }
    // Add more resources as needed
  };

  return schemas[resource]?.[operation] || z.any();
}

// Example AI usage
class AIGeneratedController {
  // AI prompt: "Create a user profile update endpoint"
  @contract(smartContract({
    operation: 'update',
    resource: 'user',
    visibility: 'private',
    rateLimit: 5
  }))
  async updateUserProfile(input: UserUpdateInput, context: AuthContext) {
    return userService.updateUser(input, context);
  }

  // AI prompt: "Create an admin user deletion endpoint"
  @contract(smartContract({
    operation: 'delete',
    resource: 'user',
    visibility: 'admin',
    rateLimit: 10
  }))
  async deleteUser(input: { userId: string }, context: AuthContext) {
    return userService.deleteUser(input.userId, context);
  }
}

🎉 What We've Mastered

In this part, we've covered:

✅ Contract Composition - Reusable, composable security patterns

✅ Conditional Contracts - Dynamic security based on context

✅ Bulk Operations - Safe handling of array data

✅ Advanced Debugging - Real-time contract execution monitoring

✅ Comprehensive Testing - Unit tests, integration tests, and mocking

✅ Performance Optimization - Contract compilation and caching

✅ AI-Friendly Patterns - Smart contract generation for AI tools

🔮 Coming in Part 5

In our final installment, we'll explore:

Production deployment strategies
AI template libraries that make secure code the default
Monitoring and alerting for contract violations
The future of AI-assisted development

Questions about the advanced patterns? Drop them in the comments! I love seeing how you adapt these to your specific use cases.

Next: The final chapter where we deploy this system to production and build an AI-friendly template library.

Building a Bulletproof Next.js User Management System with Contract Programming

meta-closure — Tue, 12 Aug 2025 13:18:53 +0000

Part 3 of 5: From theory to production-ready code that AI tools can safely contribute to

Welcome back! In Part 2, we learned the fundamentals of Decorator Contract Programming. Today, we're building a complete, production-ready user management system that's impossible for AI to break.

🎯 What We're Building

A Next.js user management system with:

✅ Multi-layer security (Presentation → Action → Business → Data)
✅ AI-proof contracts at every layer
✅ Automatic error handling and appropriate responses
✅ Complete audit trail of all operations
✅ Type safety with runtime validation

🏗️ Architecture Overview

┌─────────────────────┐
│ app/routes/*.tsx    │ ← Presentation Layer
│ (Basic auth checks) │
├─────────────────────┤
│ lib/actions/*.ts    │ ← Action Layer  
│ (Permissions & I/O) │
├─────────────────────┤
│ lib/services/*.ts   │ ← Business Layer
│ (Ownership & Rules) │
├─────────────────────┤
│ lib/data/*.ts       │ ← Data Layer
│ (Final defense)     │
└─────────────────────┘

📋 Step 1: Schema Definitions

First, let's define our data contracts with Zod:

// lib/schemas/user.ts
import { z } from 'zod';

// Input schemas
export const userUpdateSchema = z.object({
  userId: z.string().uuid('Invalid user ID format'),
  email: z.string().email('Invalid email format').optional(),
  name: z.string()
    .min(1, 'Name is required')
    .max(100, 'Name must be less than 100 characters')
    .optional(),
  role: z.enum(['user', 'admin', 'moderator']).optional()
});

export const userCreateSchema = z.object({
  email: z.string().email('Invalid email format'),
  name: z.string()
    .min(1, 'Name is required')
    .max(100, 'Name must be less than 100 characters'),
  role: z.enum(['user', 'admin', 'moderator']).default('user')
});

// Output schema
export const userOutputSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string(),
  role: z.string(),
  createdAt: z.date(),
  updatedAt: z.date()
});

// Context types
export interface AuthContext {
  user: {
    id: string;
    email: string;
    roles: string[];
  };
  session: {
    id: string;
    expiresAt: Date;
  };
}

// Type exports
export type UserUpdateInput = z.infer<typeof userUpdateSchema>;
export type UserCreateInput = z.infer<typeof userCreateSchema>;
export type User = z.infer<typeof userOutputSchema>;

🎭 Step 2: Presentation Layer

The presentation layer handles basic authentication and UI:

// app/(dashboard)/profile/page.tsx
import { redirect } from 'next/navigation';
import { updateProfile } from '@/lib/actions/users';
import { getServerSession } from 'next-auth/next';
import { authOptions } from '@/lib/auth/config';

export default async function ProfilePage() {
  const session = await getServerSession(authOptions);

  // Presentation layer: Basic auth check
  if (!session?.user) {
    redirect('/login');
  }

  if (new Date(session.expires) < new Date()) {
    redirect('/login?error=session_expired');
  }

  return (
    <div className="max-w-2xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Profile Settings</h1>

      <form action={updateProfile} className="space-y-4">
        <div>
          <label htmlFor="email" className="block text-sm font-medium mb-1">
            Email
          </label>
          <input
            id="email"
            name="email"
            type="email"
            defaultValue={session.user.email}
            className="w-full px-3 py-2 border rounded-md"
            required
          />
        </div>

        <div>
          <label htmlFor="name" className="block text-sm font-medium mb-1">
            Name
          </label>
          <input
            id="name"
            name="name"
            type="text"
            defaultValue={session.user.name}
            className="w-full px-3 py-2 border rounded-md"
            required
          />
        </div>

        <input name="userId" type="hidden" value={session.user.id} />

        <button
          type="submit"
          className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
        >
          Update Profile
        </button>
      </form>
    </div>
  );
}

⚡ Step 3: Action Layer

This is where the magic happens. The action layer handles permissions, validation, and rate limiting:

// lib/actions/users.ts
"use server";

import { getServerSession } from 'next-auth/next';
import { authOptions } from '@/lib/auth/config';
import { userService } from '@/lib/services/users';
import { redirect } from 'next/navigation';
import {
  userUpdateSchema,
  userCreateSchema,
  userOutputSchema,
  type UserUpdateInput,
  type UserCreateInput,
  type AuthContext,
  type User
} from '@/lib/schemas/user';
import { contract, auth, validates, owns, rateLimit, auditLog, returns } from '@/lib/contracts';

class UserActions {
  @contract({
    requires: [
      auth('user'),                     // Must be authenticated
      validates(userUpdateSchema),      // Input validation
      owns('userId'),                   // Must own the profile
      rateLimit('updateProfile', 5)     // Max 5 updates per minute
    ],
    ensures: [
      returns(userOutputSchema),        // Output validation
      auditLog('profile_update')        // Audit trail
    ],
    layer: 'action'
  })
  async updateProfile(
    input: UserUpdateInput,
    context: AuthContext
  ): Promise<User> {
    return userService.updateUser(input, context);
  }

  @contract({
    requires: [
      auth('admin'),                    // Admin only
      validates(userCreateSchema),      // Input validation
      rateLimit('createUser', 10)       // Max 10 creations per minute
    ],
    ensures: [
      returns(userOutputSchema),        // Output validation
      auditLog('user_creation')         // Audit trail
    ],
    layer: 'action'
  })
  async createUser(
    input: UserCreateInput,
    context: AuthContext
  ): Promise<User> {
    return userService.createUser(input, context);
  }

  @contract({
    requires: [
      auth('user'),                     // Must be authenticated
      owns('userId'),                   // Can only delete own account
      rateLimit('deleteProfile', 1)     // Max 1 deletion per minute
    ],
    ensures: [
      auditLog('profile_deletion')      // Audit trail
    ],
    layer: 'action'
  })
  async deleteProfile(
    input: { userId: string },
    context: AuthContext
  ): Promise<{ success: boolean }> {
    await userService.deleteUser(input.userId, context);
    return { success: true };
  }
}

const userActions = new UserActions();

// Server Action entry points
export const updateProfile = async (formData: FormData) => {
  try {
    const session = await getServerSession(authOptions);
    const context: AuthContext = {
      user: session?.user as any,
      session: session as any
    };

    const input: UserUpdateInput = {
      userId: formData.get('userId') as string,
      email: formData.get('email') as string,
      name: formData.get('name') as string
    };

    const result = await userActions.updateProfile(input, context);

    return { success: true, data: result };

  } catch (error) {
    if (error instanceof ContractViolationError) {
      const response = error.getAppropriateResponse();

      if (response.redirect) {
        redirect(response.redirect);
      }

      return response;
    }

    console.error('Unexpected error in updateProfile:', error);
    return { success: false, error: 'An unexpected error occurred.' };
  }
};

export const createUser = async (formData: FormData) => {
  try {
    const session = await getServerSession(authOptions);
    const context: AuthContext = {
      user: session?.user as any,
      session: session as any
    };

    const input: UserCreateInput = {
      email: formData.get('email') as string,
      name: formData.get('name') as string,
      role: (formData.get('role') as 'user' | 'admin' | 'moderator') || 'user'
    };

    const result = await userActions.createUser(input, context);
    return { success: true, data: result };

  } catch (error) {
    if (error instanceof ContractViolationError) {
      return error.getAppropriateResponse();
    }

    return { success: false, error: 'An unexpected error occurred.' };
  }
};

🧠 Step 4: Business Layer

The business layer enforces ownership and business rules:

// lib/services/users.ts
import { userRepository } from '@/lib/data/users';
import { contract, owns, businessRule } from '@/lib/contracts';
import {
  type UserUpdateInput,
  type UserCreateInput,
  type User,
  type AuthContext
} from '@/lib/schemas/user';

class UserService {
  @contract({
    requires: [
      owns('userId'),                   // Must own the resource
      businessRule('Cannot change own role', (input, context) => {
        // Users can't change their own role
        return !input.role || 
               input.userId !== context.user.id || 
               input.role === context.user.roles[0];
      }),
      businessRule('Email change frequency limit', async (input, context) => {
        // Can only change email once per 24 hours
        if (!input.email) return true;

        const user = await userRepository.findById(input.userId);
        const lastChange = user?.emailChangedAt;
        if (!lastChange) return true;

        const hoursSince = (Date.now() - lastChange.getTime()) / (1000 * 60 * 60);
        return hoursSince >= 24;
      })
    ],
    invariants: [
      // Output user ID must match input
      (input, output) => output.id === input.userId,
      // Update time must be reasonable
      (input, output) => output.updatedAt <= new Date()
    ],
    layer: 'business'
  })
  async updateUser(
    input: UserUpdateInput,
    context: AuthContext
  ): Promise<User> {
    const existingUser = await userRepository.findById(input.userId);
    if (!existingUser) {
      throw new Error('User not found');
    }

    // Business logic
    const updatedUser = {
      ...existingUser,
      ...(input.email && { email: input.email }),
      ...(input.name && { name: input.name }),
      ...(input.role && { role: input.role }),
      updatedAt: new Date(),
      ...(input.email && input.email !== existingUser.email && { 
        emailChangedAt: new Date() 
      })
    };

    // Check for email conflicts
    if (input.email && input.email !== existingUser.email) {
      const duplicate = await userRepository.findByEmail(input.email);
      if (duplicate && duplicate.id !== input.userId) {
        throw new Error('Email already in use');
      }
    }

    return userRepository.save(updatedUser, context);
  }

  @contract({
    requires: [
      businessRule('Email must be unique', async (input) => {
        const existing = await userRepository.findByEmail(input.email);
        return !existing;
      })
    ],
    invariants: [
      (input, output) => output.email === input.email,
      (input, output) => output.name === input.name,
      (input, output) => output.role === input.role
    ],
    layer: 'business'
  })
  async createUser(
    input: UserCreateInput,
    context: AuthContext
  ): Promise<User> {
    const newUser = {
      id: crypto.randomUUID(),
      email: input.email,
      name: input.name,
      role: input.role,
      userId: crypto.randomUUID(),
      createdAt: new Date(),
      updatedAt: new Date()
    };

    return userRepository.create(newUser, context);
  }

  @contract({
    requires: [
      owns('userId'),
      businessRule('Cannot delete admin users', async (userId, context) => {
        const user = await userRepository.findById(userId);
        return user?.role !== 'admin' || 
               context.user.roles.includes('super_admin');
      })
    ],
    layer: 'business'
  })
  async deleteUser(userId: string, context: AuthContext): Promise<void> {
    await userRepository.delete(userId, context);
  }
}

export const userService = new UserService();

🗄️ Step 5: Data Layer

The data layer provides the final security boundary:

// lib/data/users.ts
import { PrismaClient } from '@prisma/client';
import { contract, auditLog } from '@/lib/contracts';
import { type User, type AuthContext } from '@/lib/schemas/user';

const prisma = new PrismaClient();

class UserRepository {
  @contract({
    requires: [
      // Final data access permission check
      (input, context) => {
        return context.user.roles.includes('admin') || 
               input.id === context.user.id;
      }
    ],
    ensures: [
      // Data integrity final check
      (output, input) => output.id === input.id,
      auditLog('user_data_update')
    ],
    invariants: [
      // Saved data integrity
      (input, output) => output.updatedAt >= input.updatedAt
    ],
    layer: 'data'
  })
  async save(user: User, context: AuthContext): Promise<User> {
    const result = await prisma.user.update({
      where: { 
        id: user.id,
        // Query-level safety net
        ...(context.user.roles.includes('admin') ? {} : { id: context.user.id })
      },
      data: {
        email: user.email,
        name: user.name,
        role: user.role,
        updatedAt: user.updatedAt,
        emailChangedAt: user.emailChangedAt
      }
    });

    return result as User;
  }

  @contract({
    ensures: [
      auditLog('user_data_creation')
    ],
    invariants: [
      (input, output) => output.email === input.email,
      (input, output) => output.name === input.name
    ],
    layer: 'data'
  })
  async create(user: User, context: AuthContext): Promise<User> {
    const result = await prisma.user.create({
      data: {
        id: user.id,
        email: user.email,
        name: user.name,
        role: user.role,
        userId: user.userId,
        createdAt: user.createdAt,
        updatedAt: user.updatedAt
      }
    });

    return result as User;
  }

  @contract({
    requires: [
      // Final deletion permission check
      (input, context) => {
        return context.user.roles.includes('admin') || 
               input === context.user.id;
      }
    ],
    ensures: [
      auditLog('user_data_deletion')
    ],
    layer: 'data'
  })
  async delete(userId: string, context: AuthContext): Promise<void> {
    await prisma.user.delete({
      where: { 
        id: userId,
        // Query-level safety net
        ...(context.user.roles.includes('admin') ? {} : { id: context.user.id })
      }
    });
  }

  // Helper methods (no contracts - internal use only)
  async findById(userId: string): Promise<User | null> {
    const user = await prisma.user.findUnique({
      where: { id: userId }
    });
    return user as User | null;
  }

  async findByEmail(email: string): Promise<User | null> {
    const user = await prisma.user.findUnique({
      where: { email }
    });
    return user as User | null;
  }
}

export const userRepository = new UserRepository();

🔧 Step 6: Contract Implementation Details

Here are the missing pieces from our contract system:

// lib/contracts/index.ts
import { z } from 'zod';

// Rate limiting helper (you'd implement with Redis or similar)
const rateLimitStore = new Map<string, { count: number; resetTime: number }>();

async function getRateLimitCount(key: string): Promise<number> {
  const now = Date.now();
  const stored = rateLimitStore.get(key);

  if (!stored || now > stored.resetTime) {
    rateLimitStore.set(key, { count: 0, resetTime: now + 60000 }); // 1 minute
    return 0;
  }

  return stored.count;
}

async function incrementRateLimitCount(key: string): Promise<void> {
  const now = Date.now();
  const stored = rateLimitStore.get(key);

  if (!stored || now > stored.resetTime) {
    rateLimitStore.set(key, { count: 1, resetTime: now + 60000 });
  } else {
    stored.count++;
  }
}

// Resource ownership helper
async function getResourceById(id: string): Promise<{ id: string; userId: string } | null> {
  // This would typically query your database
  // For user resources, the user IS the resource
  try {
    const user = await prisma.user.findUnique({ where: { id } });
    return user ? { id: user.id, userId: user.id } : null;
  } catch {
    return null;
  }
}

// Audit logging helper
interface AuditEvent {
  action: string;
  userId: string;
  resourceId?: string;
  timestamp: Date;
  input: any;
  output?: any;
  success: boolean;
}

async function logAuditEvent(event: AuditEvent): Promise<void> {
  // In production, this would go to your audit log system
  console.log('AUDIT:', JSON.stringify({
    ...event,
    input: sanitizeForAudit(event.input),
    output: sanitizeForAudit(event.output)
  }));
}

function sanitizeForAudit(data: any): any {
  if (typeof data !== 'object' || data === null) {
    return data;
  }

  const sanitized = { ...data };
  // Remove sensitive fields
  delete sanitized.password;
  delete sanitized.token;
  delete sanitized.secret;

  return sanitized;
}

// Rate limit condition
export function rateLimit(operation: string, maxPerMinute: number) {
  return async (input: any, context: AuthContext): Promise<boolean> => {
    const key = `rateLimit:${context.user.id}:${operation}`;
    const current = await getRateLimitCount(key);

    if (current >= maxPerMinute) {
      throw new ContractError('RATE_LIMIT_EXCEEDED', 
        `Rate limit exceeded for ${operation}: ${current}/${maxPerMinute} per minute`);
    }

    await incrementRateLimitCount(key);
    return true;
  };
}

// Audit log condition
export function auditLog(action: string) {
  return async (output: any, input: any, context: AuthContext): Promise<boolean> => {
    await logAuditEvent({
      action,
      userId: context.user.id,
      resourceId: input.id || input.userId,
      timestamp: new Date(),
      input,
      output,
      success: true
    });
    return true;
  };
}

// Output validation condition
export function returns(schema: z.ZodSchema) {
  return (output: any, input: any, context: any): boolean => {
    try {
      schema.parse(output);
      return true;
    } catch (error) {
      throw new ContractError('OUTPUT_VALIDATION_FAILED', 
        `Output does not match expected schema: ${error.message}`);
    }
  };
}

// Business rule condition
export function businessRule(
  description: string, 
  rule: (input: any, context: AuthContext) => boolean | Promise<boolean>
) {
  return async (input: any, context: AuthContext): Promise<boolean> => {
    const passed = await rule(input, context);
    if (!passed) {
      throw new ContractError('BUSINESS_RULE_VIOLATION', description);
    }
    return true;
  };
}

✅ Step 7: Testing Your Secure System

// __tests__/user-actions.test.ts
import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { UserActions } from '@/lib/actions/users';
import { ContractViolationError } from '@/lib/contracts';

describe('UserActions', () => {
  let userActions: UserActions;
  let mockContext: AuthContext;

  beforeEach(() => {
    userActions = new UserActions();
    mockContext = {
      user: { id: 'user-123', email: 'user@test.com', roles: ['user'] },
      session: { id: 'session-123', expiresAt: new Date(Date.now() + 3600000) }
    };
  });

  describe('updateProfile', () => {
    it('should successfully update own profile', async () => {
      const input = {
        userId: 'user-123',
        email: 'newemail@test.com',
        name: 'New Name'
      };

      const result = await userActions.updateProfile(input, mockContext);

      expect(result.email).toBe('newemail@test.com');
      expect(result.name).toBe('New Name');
    });

    it('should fail when trying to update other user profile', async () => {
      const input = {
        userId: 'user-456', // Different user
        email: 'newemail@test.com',
        name: 'New Name'
      };

      await expect(userActions.updateProfile(input, mockContext))
        .rejects
        .toThrow(ContractViolationError);
    });

    it('should fail with invalid email format', async () => {
      const input = {
        userId: 'user-123',
        email: 'invalid-email',
        name: 'New Name'
      };

      await expect(userActions.updateProfile(input, mockContext))
        .rejects
        .toThrow('Input validation failed');
    });
  });
});

🎉 What We've Accomplished

Our system now has:

✅ 4-layer security - Each layer catches what others miss

✅ Automatic validation - Zod schemas catch malformed input

✅ Ownership checks - Users can only modify their own data

✅ Rate limiting - Prevents abuse and DoS attacks

✅ Complete audit trail - Every action is logged

✅ Graceful error handling - Appropriate responses per layer

🤖 The AI Advantage

Here's the beautiful part: AI tools can now safely contribute to this codebase. When you ask Claude to "add a feature to delete user posts", it will:

Copy the contract patterns it sees everywhere
Follow the layer structure that's clearly defined
Generate secure code because insecure code won't deploy

The contracts guide AI toward secure implementations automatically.

🔮 Coming Next

In Part 4, we'll explore advanced patterns:

Contract composition and inheritance
Conditional contracts for complex business rules
Testing strategies for contract-based systems
Performance optimization techniques

Questions about the implementation? Drop them below! I'd love to help you adapt this to your specific use case.

Next up: Advanced contract patterns that handle the most complex business scenarios.

Decorator Contract Programming: Making AI-Generated Code Bulletproof

meta-closure — Tue, 12 Aug 2025 13:15:09 +0000

Part 2 of 5: Building a Zero-Trust Architecture that AI tools can't break

Welcome back to our AI security series! In Part 1, we saw how AI-generated code can create critical security vulnerabilities. Today, we're going to fix that with a revolutionary approach: Decorator Contract Programming.

🎯 The Core Problem

AI tools generate code that works, but they don't understand:

Layer responsibilities (where should auth checks go?)
Cross-cutting concerns (logging, validation, rate limiting)
Business rules (who can access what?)
Security boundaries (trust nothing, verify everything)

Traditional solutions fail because they expect AI to be smart about security. Spoiler alert: It's not.

💡 The Breakthrough: Contracts as Code

Instead of hoping AI gets security right, we make security violations impossible to deploy.

The secret? Declarative contracts that tell the system exactly what must be true before, during, and after each function call.

@contract({
  requires: [auth('user'), validates(schema), owns('userId')],
  ensures: [auditLog('action'), returns(outputSchema)]
})
async function dangerousFunction(input, context) {
  // Even if AI writes terrible code here,
  // the contract catches violations
}

🏗️ Zero-Trust Layer Architecture

Here's the architecture that changes everything:

┌─────────────────┐
│ Presentation    │ ← Basic auth (login status, session)
├─────────────────┤
│ Action          │ ← Permissions (roles, rate limits, input validation)
├─────────────────┤
│ Business        │ ← Ownership (resource access, business rules)
├─────────────────┤
│ Data            │ ← Final defense (query-level security, audit)
└─────────────────┘

Key insight: Even if AI misses security in one layer, the other layers catch it.

🔧 Building Your First Contract

Let's start simple. Here's how to create a basic contract system:

Step 1: Define Contract Types

type ContractCondition = (input: any, context: any) => boolean | Promise<boolean>;
type ContractValidator = (input: unknown) => any;

interface ContractOptions {
  requires?: Array<ContractCondition | ContractValidator>;
  ensures?: Array<(output: any, input: any, context: any) => boolean>;
  layer?: 'presentation' | 'action' | 'business' | 'data';
}

Step 2: Create the Contract Decorator

function contract(options: ContractOptions) {
  return function(target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;

    descriptor.value = async function(...args: any[]) {
      const [input, context] = args;

      try {
        // Pre-conditions (requires)
        let validatedInput = input;
        for (const condition of options.requires || []) {
          if (typeof condition === 'function' && condition.length === 1) {
            // Validator - transforms input
            validatedInput = condition(validatedInput);
          } else {
            // Condition check
            await condition(validatedInput, context);
          }
        }

        // Execute original method
        const result = await originalMethod.call(this, validatedInput, context);

        // Post-conditions (ensures)
        for (const condition of options.ensures || []) {
          await condition(result, validatedInput, context);
        }

        return result;

      } catch (error) {
        throw new ContractViolationError(
          `${target.constructor.name}.${propertyName}`,
          options.layer || 'unknown',
          error
        );
      }
    };
  };
}

Step 3: Build Contract Conditions

// Authentication check
function auth(requiredRole?: string) {
  return async (input: any, context: AuthContext): Promise<boolean> => {
    if (!context.user) {
      throw new ContractError('AUTHENTICATION_REQUIRED', 'User must be logged in');
    }

    if (!context.session || new Date(context.session.expiresAt) < new Date()) {
      throw new ContractError('SESSION_EXPIRED', 'Session has expired');
    }

    if (requiredRole && !context.user.roles.includes(requiredRole)) {
      throw new ContractError('INSUFFICIENT_ROLE', 
        `Required role: ${requiredRole}`);
    }

    return true;
  };
}

// Ownership validation
function owns(resourceIdField: string) {
  return async (input: any, context: AuthContext): Promise<boolean> => {
    const resourceId = input[resourceIdField];
    if (!resourceId) {
      throw new ContractError('MISSING_RESOURCE_ID', 
        `Field ${resourceIdField} is required`);
    }

    // Admin users can access all resources
    if (context.user.roles.includes('admin')) {
      return true;
    }

    // Check resource ownership
    const resource = await getResourceById(resourceId);
    if (!resource || resource.userId !== context.user.id) {
      throw new ContractError('OWNERSHIP_DENIED', 
        `User ${context.user.id} does not own resource ${resourceId}`);
    }

    return true;
  };
}

// Input validation
function validates(schema: z.ZodSchema) {
  return (input: unknown): any => {
    try {
      return schema.parse(input);
    } catch (error) {
      if (error instanceof z.ZodError) {
        const messages = error.issues.map(issue => 
          `${issue.path.join('.')}: ${issue.message}`
        ).join(', ');
        throw new ContractError('VALIDATION_FAILED', 
          `Input validation failed: ${messages}`);
      }
      throw error;
    }
  };
}

Step 4: Handle Contract Violations

class ContractError extends Error {
  constructor(public type: string, message: string) {
    super(message);
    this.name = 'ContractError';
  }
}

class ContractViolationError extends Error {
  constructor(
    public contractName: string,
    public layer: string,
    public originalError: any
  ) {
    super(`Contract violation in ${layer}.${contractName}: ${originalError.message}`);
    this.name = 'ContractViolationError';
  }

  getAppropriateResponse() {
    switch (this.layer) {
      case 'presentation':
        return { redirect: '/login', error: 'Authentication required' };
      case 'action':
        return { success: false, error: this.originalError.message };
      case 'business':
        return { success: false, error: 'Permission denied' };
      case 'data':
        return { success: false, error: 'Operation failed' };
      default:
        return { success: false, error: 'An error occurred' };
    }
  }
}

🎪 See It In Action

Now let's transform that dangerous AI-generated function:

Before (AI-generated, vulnerable):

export async function updateUserProfile(formData: FormData) {
  const userId = formData.get('userId') as string;
  const email = formData.get('email') as string;
  const name = formData.get('name') as string;

  const updatedUser = await db.user.update({
    where: { id: userId },
    data: { email, name }
  });

  return { success: true, user: updatedUser };
}

After (contract-protected):

const userUpdateSchema = z.object({
  userId: z.string().uuid(),
  email: z.string().email().optional(),
  name: z.string().min(1).max(100).optional()
});

@contract({
  requires: [
    auth('user'),                    // Must be authenticated
    validates(userUpdateSchema),     // Input validation
    owns('userId')                   // Must own the profile
  ],
  ensures: [
    auditLog('profile_update')       // Log the action
  ],
  layer: 'action'
})
export async function updateUserProfile(
  input: UserUpdateInput, 
  context: AuthContext
): Promise<User> {
  return userService.updateUser(input, context);
}

🚀 The Magic

What happens when someone tries to hack this?

No auth token? → Contract throws AUTHENTICATION_REQUIRED
Invalid email format? → Contract throws VALIDATION_FAILED
Trying to update someone else's profile? → Contract throws OWNERSHIP_DENIED
Everything succeeds? → Action is automatically logged for audit

The AI doesn't need to know about security. The contract handles everything.

🎯 Why This Works With AI

AI tools love this approach because:

Declarative: Clear requirements, no ambiguity
Copy-pasteable: Perfect patterns to replicate
Composable: Mix and match contract pieces
Fail-safe: Violations are caught automatically

Instead of teaching AI complex security concepts, we give it simple, repeatable patterns.

🔮 Coming Up

In Part 3, we'll build a complete Next.js user management system using these contracts. You'll see how to:

Structure your layers properly
Handle different types of operations
Integrate with Next.js Server Actions
Make it production-ready

Questions or ideas? Drop them in the comments! I love seeing how you adapt these patterns.

Don't miss Part 3: We're building a real-world system that AI tools can contribute to safely.

The AI Code Generation Security Crisis (And How We're Failing to Address It)

meta-closure — Mon, 11 Aug 2025 16:49:22 +0000

How I watched Claude create 50 lines of perfect code in 10 seconds... and 3 critical security vulnerabilities along with it.

🚨 The 10-Second Nightmare

Last Tuesday, I was pair programming with Claude (yes, the AI). I asked it to create a simple user profile update API for our Next.js app.

What happened next was both amazing and terrifying.

In 10 seconds, Claude generated this beautiful, clean code:

// AI generated this in 10 seconds ⚡
export async function updateUserProfile(formData: FormData) {
  const userId = formData.get('userId') as string;
  const email = formData.get('email') as string;
  const name = formData.get('name') as string;

  const updatedUser = await db.user.update({
    where: { id: userId },
    data: { email, name }
  });

  return { success: true, user: updatedUser };
}

It looked perfect. Clean, concise, exactly what I asked for. It would have taken me 30 minutes to write and test this manually.

But then I realized the horror: This innocent-looking function had 3 critical security vulnerabilities that could expose our entire user database.

💀 The Hidden Vulnerabilities

Let me show you what the AI missed:

1. Zero Authentication

// Anyone can call this - even unauthenticated users
export async function updateUserProfile(formData: FormData) {
  // No auth check whatsoever 😱

2. No Ownership Validation

// User A can update User B's profile
const userId = formData.get('userId') as string;
await db.user.update({
  where: { id: userId }, // Any user ID works!
  data: { email, name }
});

3. Missing Input Validation

// Injection paradise
const email = formData.get('email') as string; // Could be anything
const name = formData.get('name') as string;   // Could be <script>alert('xss')</script>

In a real app, this would be game over:

✅ Attackers could modify anyone's email address
✅ No audit trail of who changed what
✅ Input validation completely bypassed
✅ Rate limiting? What's that?

📊 This Isn't Just My Problem

I'm not alone in this struggle. Recent data shows:

97% of developers have used AI coding tools at work, with 47% of US and German developers using time saved by AI for collaboration and system design (GitHub 2024 AI in Software Development Survey).
AI-assisted code is less secure, with only 3% of AI-generated code secure in authentication-related tasks compared to 21% without AI, and 36% of AI-assisted SQL code vulnerable to injections versus 7% without AI (Stanford 2022 Study).
Security issues in AI-assisted projects often stem from risks like prompt injection and supply-chain vulnerabilities, with no specific percentage tied to missing guardrails (OWASP 2025 AI Security Resources).

The problem? AI tools are trained to make code work, not to make it secure.

They excel at:

✅ Generating syntactically correct code
✅ Following basic patterns
✅ Implementing happy-path logic

They struggle with:

❌ Security-first thinking
❌ Cross-cutting concerns
❌ Layer responsibility separation
❌ Business rule enforcement

🤔 Why Traditional Solutions Don't Work

You might be thinking: "Just use ESLint rules!" or "Better PR reviews will catch this!"

I tried everything:

ESLint Rules ❌

// .eslintrc.js
{
  "rules": {
    "auth-required": "error",
    "input-validation": "error"
  }
}

Reality: ESLint can't understand business logic. It can't know that updateUserProfile needs ownership checks.

TypeScript Types ❌

type AuthenticatedRequest = {
  user: User;
  // ...
}

Reality: AI tools often bypass or ignore complex type constraints when generating code quickly.

PR Reviews ❌

Reality: When AI generates 200 lines across 10 files in 30 seconds, human reviewers miss the subtle security gaps. We're just not fast enough.

Documentation ❌

Reality: AI tools don't consistently follow security documentation, especially under time pressure.

🚀 The Real Solution (Sneak Peek)

After months of frustration, I discovered a pattern that actually works: Decorator Contract Programming.

The idea is simple: Make security violations impossible to deploy, not just hard to write.

Here's the same function, but AI-proof:

@contract({
  requires: [
    auth('user'),                    // Must be authenticated
    validates(userUpdateSchema),     // Input validation required
    owns('userId'),                  // Must own the resource
    rateLimit('updateProfile', 5)    // Rate limiting enforced
  ],
  ensures: [
    auditLog('profile_update'),      // Audit trail created
    returns(userOutputSchema)        // Output validation
  ]
})
export async function updateUserProfile(
  input: UserUpdateInput, 
  context: AuthContext
) {
  return userService.updateUser(input, context);
}

What happens now?

✅ Runtime Protection: If auth fails → automatic 401 redirect
✅ Input Validation: Invalid data → detailed error messages
✅ Ownership Checks: Wrong user → permission denied
✅ Audit Logging: Every action → automatically logged
✅ Rate Limiting: Too many requests → throttled

The beauty? AI tools can copy-paste these contract patterns perfectly. They love repetitive, declarative code.

🔮 What's Coming

In this 5-part series, I'll show you exactly how to:

Part 1 (this): The AI security crisis we're facing
Part 2: Introduction to Decorator Contract Programming
Part 3: Building a real Next.js user management system
Part 4: Advanced patterns and testing strategies
Part 5: AI-friendly templates and production deployment

Next: We'll dive deep into the core concepts of Decorator Contract Programming and build our first secure AI-proof function.

💭 Your Turn

Have you encountered security issues with AI-generated code?

Drop your horror stories in the comments. Let's learn from each other's mistakes before they become production incidents.

Found this helpful? Hit that ❤️ and follow me for the rest of this series!