Security

Production hardening and security best practices for FOON.

Security Options

FOON provides built-in security features through the security option:

import { transform, OpenAIProvider } from 'foon-sdk';

const result = await transform(input, {
  schema,
  provider: new OpenAIProvider({
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-5-nano'
  }),
  security: {
    maxInputSize: 1024 * 1024,    // 1MB default
    maxDepth: 10,                  // Max nesting depth
    maxKeys: 1000,                 // Max number of keys
    redactKeys: ['password', 'token', 'apiKey'],
    sanitizePrompt: true,          // Prompt injection protection
    includeValues: false           // Don't send values to LLM
  }
});

Data Redaction

Prevent sensitive data from being sent to AI providers:

const result = await transform(input, {
  schema,
  provider,
  security: {
    redactKeys: ['password', 'ssn', 'creditCard', 'apiKey', 'secret']
  }
});

How Redaction Works

Before sending to AI, sensitive fields are replaced with placeholders
AI generates mapping plan using structure only
Actual transform uses real values (never sent to AI)

Structure-Only Mode

For maximum privacy, don't send any values to the LLM:

const result = await transform(input, {
  schema,
  provider,
  security: {
    includeValues: false  // Only send field structure, not values
  }
});

Input Limits

Protect against malicious payloads:

const result = await transform(input, {
  schema,
  provider,
  security: {
    maxInputSize: 1024 * 1024,  // 1MB max input size
    maxDepth: 10,                // Max nesting depth
    maxKeys: 1000                // Max number of keys
  }
});

Limit Violations

When limits are exceeded, the transform fails with SECURITY_LIMIT_EXCEEDED:

const result = await transform(largePayload, { schema, provider, security });

if (!result.ok && result.error?.category === 'SECURITY_LIMIT_EXCEEDED') {
  console.log('Input exceeded security limits');
  console.log(result.error.message);
}

Prompt Safety

Enable sanitization to protect against prompt injection:

const result = await transform(input, {
  schema,
  provider,
  security: {
    sanitizePrompt: true  // Default: true
  }
});

This helps prevent malicious input like:

"ignore previous instructions"
Embedded system prompts
Jailbreak attempts

Confidence Threshold

Reject low-confidence mappings to ensure accuracy:

const result = await transform(input, {
  schema,
  provider,
  confidenceThreshold: 0.9  // Reject mappings below 90%
});

if (!result.ok && result.error?.category === 'CONFIDENCE_TOO_LOW') {
  console.log('Mapping confidence too low');
  console.log(result.trace.confidenceSummary);
}

Audit Logging with Hooks

Track all transformations using hooks:

const result = await transform(input, {
  schema,
  provider,
  hooks: {
    onComplete: async (result) => {
      await auditLog.write({
        timestamp: new Date(),
        traceId: result.trace.traceId,
        timings: result.trace.timings,
        cacheHit: result.trace.cache.hit,
        confidence: result.trace.confidenceSummary
      });
    },
    onError: async (error) => {
      await auditLog.write({
        timestamp: new Date(),
        error: error.category,
        message: error.message
      });
    }
  }
});

Environment Variables

Never hardcode API keys:

// Good
const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-5-nano'
});

// Bad - never do this
const provider = new OpenAIProvider({
  apiKey: 'sk-...'  // Don't hardcode!
});

Express Security

When using the Express integration, security options apply to all routes:

import { createFonRouter } from 'foon-sdk/express';
import { OpenAIProvider } from 'foon-sdk';

const fonRouter = createFonRouter({
  provider: new OpenAIProvider({
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-5-nano'
  }),
  confidenceThreshold: 0.85,
  security: {
    maxInputSize: 1024 * 1024,
    maxDepth: 10,
    maxKeys: 1000,
    redactKeys: ['password', 'token'],
    sanitizePrompt: true
  }
});

Production Checklist

[ ] API keys in environment variables
[ ] Sensitive field redaction enabled (redactKeys)
[ ] Input size limits configured (maxInputSize, maxDepth, maxKeys)
[ ] Prompt sanitization enabled (sanitizePrompt: true)
[ ] Appropriate confidence threshold set
[ ] Audit logging implemented with hooks
[ ] Error handling for all transform calls
[ ] Monitoring and alerting set up