@illuma-ai/gateway-core

Standalone API gateway for the Illuma platform — powers Illuma Code, Illuma Desktop, and Illuma Chat from a single OpenAI-compatible surface backed by AWS Bedrock.

Zero host imports. Everything flows in through a dependency-injection contract (GatewayDeps) so the same package ships as:

1. Embedded inside a host application that provides auth, config, and credentials
2. Standalone as a dedicated ECS/Fargate service

Features

• OpenAI-compatible /v1/chat/completions — streaming + non-streaming, tool calls, reasoning, over AWS Bedrock Converse
• Native Bedrock passthrough (/bedrock/converse) — lower-overhead NDJSON stream for advanced clients
• Image generation (/v1/images/generations) — Amazon Nova Canvas, Titan, Stability Stable Image Core / Ultra / SD3 / SDXL, with per-region Bedrock client cache and catalog-driven region auto-resolution
• Device authorization — OAuth 2.0 Device Flow with Redis-backed state and atomic Lua approve/deny
• Pluggable tracing — ships createNoopTracer() by default; createOtelTracer() streams LLM and image spans to Illuma Observe (Langfuse-compatible) when ILLUMA_PUBLIC_KEY / ILLUMA_SECRET_KEY / ILLUMA_BASE_URL are set on the host
• Client attribution — clientAttributionMiddleware reads X-ILLUMA-CLIENT and X-ILLUMACODE-* headers and labels every span with client.source, client.organization_id, client.task_id, client.project_id, client.editor

Install

npm install @illuma-ai/gateway-core

Peer dependency: express ^4.18 || ^5.

Quick start

import express from 'express';
import { createGatewayRouter, createOtelTracer } from '@illuma-ai/gateway-core';

const app = express();
app.use(express.json());

const tracer = await createOtelTracer({ serviceName: 'illuma-gateway' });

const gateway = createGatewayRouter({
  requireAuth: myJwtMiddleware,
  getUserById,
  getAppConfig,
  getModelMaxTokens,
  getModelMaxOutputTokens,
  logger,
  redis,
  config: {
    jwtSecret: process.env.JWT_SECRET!,
    jwtRefreshSecret: process.env.JWT_REFRESH_SECRET!,
    extensionTokenExpiryDays: 30,
    domainClient: process.env.DOMAIN_CLIENT!,
    awsRegion: process.env.AWS_REGION ?? 'us-east-1',
    bedrockImageCredentials: process.env.BEDROCK_AWS_ACCESS_KEY_ID
      ? {
          accessKeyId: process.env.BEDROCK_AWS_ACCESS_KEY_ID,
          secretAccessKey: process.env.BEDROCK_AWS_SECRET_ACCESS_KEY!,
          sessionToken: process.env.BEDROCK_AWS_SESSION_TOKEN,
        }
      : undefined,
  },
  tracer,
});

app.use('/api/device-auth', gateway.deviceAuth);
app.use('/api/openrouter', gateway.openrouter);
app.use('/api/openrouter', gateway.images);
app.use('/api/profile', gateway.profile);
app.use('/api/users', gateway.users);
app.get('/extension-config.json', gateway.extensionConfig);

Image generation

import { createImageService, BedrockImageModels } from '@illuma-ai/gateway-core';

const service = createImageService({
  logger,
  credentials: bedrockCreds,
  fallbackRegion: 'us-east-1',
  tracer, // optional — noop by default
});

const result = await service.generateImages({
  body: { prompt: 'a neon sunset over Mount Fuji', size: '1024x1024', n: 1 },
  config: {
    enabled: true,
    provider: 'bedrock',
    model: BedrockImageModels.STABLE_IMAGE_CORE_V1_1,
  },
  userId: 'user-42',
  client: { source: 'illuma-desktop' },
});
// → { created, data: [{ b64_json }, ...] }

The catalog auto-routes Stability models to us-west-2 and Amazon models to us-east-1 without the operator setting region.

Tracing + Observe

When ILLUMA_PUBLIC_KEY, ILLUMA_SECRET_KEY, and ILLUMA_BASE_URL are set on the host, createOtelTracer() wires up @illuma-ai/observability-otel and every LLM + image call emits a span to Illuma Observe with:

• gen_ai.system, gen_ai.request.model, gen_ai.usage.*
• gateway.streaming, gateway.total_ms, gateway.ttft_ms
• gateway.image.region, gateway.image.n, gateway.image.prompt_length
• client.source, client.organization_id, client.task_id, client.project_id, client.editor

client.source lets you filter Observe dashboards by host client (illuma-desktop, illuma-code, illuma-chat).

Testing

npm install
npm run build
npx jest --no-coverage

124 tests across 14 suites — unit (adapters, normalization, client-attribution, device codes, token generator, SSE, reasoning, message converter, model registry) plus integration (device auth, profile, images, factory) with supertest.

License

Apache-2.0 — see LICENSE.