Configuration Reference - KoruAI Documentation

This page provides a comprehensive reference for all KoruAI configuration options, environment variables, and advanced settings.

Configuration Object

The KoruAI middleware accepts a configuration object with the following parameters:

Required Parameters

apiKey

string

required

Your KoruAI API key for authentication with KoruAI servers. Example: "koru_api_1234567890abcdef"

Keep this secret and never expose it in client-side code.

appId

string

required

Your application ID for identifying your app in the KoruAI system. Example: "app_9876543210fedcba"

Optional Parameters

blockRealtime

boolean

default:"false"

Whether to check for anomalies in real-time and block suspicious requests.

true: Middleware will check for anomalies in real-time and block requests if anomalies are detected
false: Middleware will send request data to KoruAI servers for analysis and dashboard reporting only

Example:

KoruAI({
  apiKey: process.env.KORUAI_API_KEY,
  appId: process.env.KORUAI_APP_ID,
  blockRealtime: true, // Enable real-time blocking
})

Environment Variables

Required Environment Variables

# Your KoruAI API key
KORUAI_API_KEY=your-api-key-here

# Your application ID
KORUAI_APP_ID=your-app-id-here

Optional Environment Variables

# Environment-specific configuration
NODE_ENV=production

# Custom KoruAI server endpoint (for enterprise customers)
KORUAI_ENDPOINT=https://custom.getkoru.ai

# Debug logging (development only)
KORUAI_DEBUG=true

Configuration Examples

Basic Configuration

The minimal configuration required to get started:

import KoruAI from "koruai";

app.use(
  KoruAI({
    apiKey: process.env.KORUAI_API_KEY,
    appId: process.env.KORUAI_APP_ID,
  })
);

Production Configuration

Recommended configuration for production environments:

import KoruAI from "koruai";

const koruaiConfig = {
  apiKey: process.env.KORUAI_API_KEY,
  appId: process.env.KORUAI_APP_ID,
  blockRealtime: true, // Enable real-time protection in production
};

// Validate configuration
if (!koruaiConfig.apiKey || !koruaiConfig.appId) {
  throw new Error("KoruAI configuration missing. Check environment variables.");
}

app.use(KoruAI(koruaiConfig));

Environment-Specific Configuration

Different settings for different environments:

import KoruAI from "koruai";

const getKoruAIConfig = () => {
  const baseConfig = {
    apiKey: process.env.KORUAI_API_KEY,
    appId: process.env.KORUAI_APP_ID,
  };

  switch (process.env.NODE_ENV) {
    case "production":
      return {
        ...baseConfig,
        blockRealtime: true, // Block threats in production
      };

    case "staging":
      return {
        ...baseConfig,
        blockRealtime: true, // Test blocking in staging
      };

    case "development":
    default:
      return {
        ...baseConfig,
        blockRealtime: false, // Only monitor in development
      };
  }
};

app.use(KoruAI(getKoruAIConfig()));

Conditional Integration

Enable KoruAI only when needed:

import KoruAI from "koruai";

// Only use KoruAI in non-test environments
if (process.env.NODE_ENV !== "test") {
  app.use(
    KoruAI({
      apiKey: process.env.KORUAI_API_KEY,
      appId: process.env.KORUAI_APP_ID,
      blockRealtime: process.env.NODE_ENV === "production",
    })
  );
}

Security Configuration

API Key Management

Development Keys

Use separate API keys for development environments with limited permissions

Production Keys

Use production keys only in production with full security features enabled

Key Rotation Strategy

// config/koruai.js
const getKoruAIConfig = () => {
  // Support for key rotation
  const apiKey = process.env.KORUAI_API_KEY_NEW || process.env.KORUAI_API_KEY;

  if (!apiKey) {
    throw new Error("No KoruAI API key found");
  }

  return {
    apiKey,
    appId: process.env.KORUAI_APP_ID,
    blockRealtime: process.env.NODE_ENV === "production",
  };
};

export default getKoruAIConfig;

Real-time Blocking Configuration

Understanding Real-time Blocking

When blockRealtime is enabled:

Request Analysis: Each request is analyzed against your custom AI-generated policies
Instant Decision: Anomalies are detected in real-time (< 1ms)
Automatic Blocking: Suspicious requests receive a 403 response
Zero Latency: Normal requests pass through with 0ms added latency

Blocking Response Format

When a request is blocked, KoruAI returns:

{
  "message": "Anomaly Detected."
}

HTTP Status Code: 403 Forbidden

Custom Blocking Responses

Currently, KoruAI uses a standard blocking response. For custom responses, you can implement additional middleware:

app.use(
  KoruAI({
    apiKey: process.env.KORUAI_API_KEY,
    appId: process.env.KORUAI_APP_ID,
    blockRealtime: true,
  })
);

// Custom error handling for blocked requests
app.use((err, req, res, next) => {
  if (res.statusCode === 403) {
    return res.status(403).json({
      error: "Request blocked by security policy",
      timestamp: new Date().toISOString(),
      requestId: req.headers["x-request-id"],
    });
  }
  next(err);
});

Performance Configuration

High Traffic Optimization

KoruAI is optimized for high-traffic applications:

// No special configuration needed for high traffic
app.use(
  KoruAI({
    apiKey: process.env.KORUAI_API_KEY,
    appId: process.env.KORUAI_APP_ID,
    blockRealtime: true, // Even blocking has minimal performance impact
  })
);

Memory Management

KoruAI automatically manages memory efficiently:

Minimal footprint: < 1MB memory usage
No request queuing: Asynchronous processing prevents memory buildup
Automatic cleanup: Request data is processed and released immediately

Monitoring and Debugging

Debug Configuration

Enable detailed logging for troubleshooting:

const koruaiConfig = {
  apiKey: process.env.KORUAI_API_KEY,
  appId: process.env.KORUAI_APP_ID,
  blockRealtime: process.env.NODE_ENV === "production",
};

// Debug logging in development
if (process.env.NODE_ENV === "development") {
  console.log("KoruAI initialized with config:", {
    apiKey: koruaiConfig.apiKey
      ? `${koruaiConfig.apiKey.slice(0, 8)}...`
      : "missing",
    appId: koruaiConfig.appId
      ? `${koruaiConfig.appId.slice(0, 8)}...`
      : "missing",
    blockRealtime: koruaiConfig.blockRealtime,
  });
}

app.use(KoruAI(koruaiConfig));

Health Check Integration

Monitor KoruAI status in your health checks:

app.get("/health", (req, res) => {
  const health = {
    status: "healthy",
    timestamp: new Date().toISOString(),
    koruai: {
      configured: !!(process.env.KORUAI_API_KEY && process.env.KORUAI_APP_ID),
      blocking: process.env.NODE_ENV === "production",
    },
  };

  res.json(health);
});

Configuration Validation

Runtime Validation

Validate your configuration at startup:

const validateKoruAIConfig = (config) => {
  const errors = [];

  if (!config.apiKey) {
    errors.push("KORUAI_API_KEY is required");
  }

  if (!config.appId) {
    errors.push("KORUAI_APP_ID is required");
  }

  if (config.apiKey && !config.apiKey.startsWith("koru_")) {
    errors.push("Invalid API key format");
  }

  if (errors.length > 0) {
    throw new Error(`KoruAI configuration errors: ${errors.join(", ")}`);
  }

  return true;
};

const koruaiConfig = {
  apiKey: process.env.KORUAI_API_KEY,
  appId: process.env.KORUAI_APP_ID,
  blockRealtime: process.env.NODE_ENV === "production",
};

validateKoruAIConfig(koruaiConfig);
app.use(KoruAI(koruaiConfig));

TypeScript Configuration

For TypeScript projects, ensure proper typing:

import KoruAI from "koruai";
import { KoruAIMiddlewareConfig } from "koruai/types";

const koruaiConfig: KoruAIMiddlewareConfig = {
  apiKey: process.env.KORUAI_API_KEY!,
  appId: process.env.KORUAI_APP_ID!,
  blockRealtime: process.env.NODE_ENV === "production",
};

app.use(KoruAI(koruaiConfig));

Best Practices

Configuration Management

Use environment-specific configurations

Validate configuration at startup

Implement graceful degradation

Monitor configuration changes

Security Considerations

Never log API keys: Ensure API keys are never written to logs or error messages
Use secure storage: Store API keys in secure configuration management systems
Regular rotation: Rotate API keys regularly and have a process for emergency rotation
Principle of least privilege: Use different keys with appropriate permissions for different environments

Troubleshooting

Common Configuration Issues

Invalid API key format

Missing environment variables

Real-time blocking not working

Next Steps

Integration Setup

Go back to the setup guide for implementation details

Quick Start Guide

Get started with KoruAI in 6 simple steps

Introduction

Integration

​Configuration Object

​Required Parameters

​Optional Parameters

​Environment Variables

​Required Environment Variables

​Optional Environment Variables

​Configuration Examples

​Basic Configuration

​Production Configuration

​Environment-Specific Configuration

​Conditional Integration

​Security Configuration

​API Key Management

Development Keys

Production Keys

​Key Rotation Strategy

​Real-time Blocking Configuration

​Understanding Real-time Blocking

​Blocking Response Format

​Custom Blocking Responses

​Performance Configuration

​High Traffic Optimization

​Memory Management

​Monitoring and Debugging

​Debug Configuration

​Health Check Integration

​Configuration Validation

​Runtime Validation

​TypeScript Configuration

​Best Practices

​Configuration Management

​Security Considerations

​Troubleshooting

​Common Configuration Issues

​Next Steps

Integration Setup

Quick Start Guide

Configuration Object

Required Parameters

Optional Parameters

Environment Variables

Required Environment Variables

Optional Environment Variables

Configuration Examples

Basic Configuration

Production Configuration

Environment-Specific Configuration

Conditional Integration

Security Configuration

API Key Management

Key Rotation Strategy

Real-time Blocking Configuration

Understanding Real-time Blocking

Blocking Response Format

Custom Blocking Responses

Performance Configuration

High Traffic Optimization

Memory Management

Monitoring and Debugging

Debug Configuration

Health Check Integration

Configuration Validation

Runtime Validation

TypeScript Configuration

Best Practices

Configuration Management

Security Considerations

Troubleshooting

Common Configuration Issues

Next Steps