@strand-js/openai 0.1.4 → 0.1.6

package/README.md

@@ -34,7 +34,53 @@ export const POST = createStrandRoute({
 })
 ```
 
-### Switching from Anthropic
+## Production security checklist
+
+Before going live, configure these options:
+
+```ts
+createStrandHandler({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o',
+
+  // 1. REQUIRED: authenticate every request
+  // Without this, anyone can hit your endpoint and burn your API credits.
+  authorize: async (request) => {
+    const token = request.headers.get('authorization')?.replace('Bearer ', '')
+    const user = await verifyToken(token)
+    if (!user) throw new Error('Unauthorized') // returns 401, no LLM call is made
+  },
+
+  // 2. RECOMMENDED: built-in rate limiting by IP
+  rateLimit: {
+    windowMs: 60_000,   // 1 minute window
+    maxRequests: 20,    // max 20 requests per IP per minute
+  },
+
+  // 3. RECOMMENDED: limit message size
+  maxMessages: 50,
+  maxMessageLength: 10_000,
+})
+```
+
+**Also configure on your server (outside Strand):**
+- **CORS** — restrict which origins can call your endpoint
+- **HTTPS** — never run in production over HTTP
+
+## What `authorize` is
+
+`authorize` runs before any LLM call. If it throws, the request is rejected with a 401 and no API credits are used.
+
+```ts
+// JWT example
+authorize: async (request) => {
+  const token = request.headers.get('authorization')?.replace('Bearer ', '')
+  const user = await verifyJWT(token)
+  if (!user) throw new Error('Unauthorized')
+}
+```
+
+## Switching providers
 
 Only the server changes — the React hooks are identical:
 
@@ -50,4 +96,19 @@ Only the server changes — the React hooks are identical:
   })
 ```
 
+## Config reference
+
+| Option | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | Your OpenAI API key |
+| `model` | `string` | Model ID, e.g. `'gpt-4o'` |
+| `system` | `string \| (req) => string` | System prompt |
+| `tools` | `ToolDefinition[]` | Tools available to the model |
+| `onToolCall` | `async (name, args, ctx) => result` | Server-side tool execution |
+| `authorize` | `async (req) => void` | Throw to reject with 401 |
+| `rateLimit` | `{ windowMs, maxRequests }` | Built-in IP rate limiting |
+| `maxMessages` | `number` | Max messages per request (default: 100) |
+| `maxMessageLength` | `number` | Max chars per message (default: 50,000) |
+| `maxSteps` | `number` | Max tool call rounds (default: 10) |
+
 [Full documentation →](https://github.com/strand-js/strand)

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ToolDefinition, Session } from '@strand-js/core';
+import { ToolDefinition, RateLimitConfig, Session } from '@strand-js/core';
 
 interface StrandHandlerConfig {
     apiKey: string;
@@ -9,6 +9,7 @@ interface StrandHandlerConfig {
         request: Request;
     }) => Promise<unknown>;
     authorize?: (request: Request) => Promise<unknown> | unknown;
+    rateLimit?: RateLimitConfig;
     maxMessages?: number;
     maxMessageLength?: number;
     maxSteps?: number;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ToolDefinition, Session } from '@strand-js/core';
+import { ToolDefinition, RateLimitConfig, Session } from '@strand-js/core';
 
 interface StrandHandlerConfig {
     apiKey: string;
@@ -9,6 +9,7 @@ interface StrandHandlerConfig {
         request: Request;
     }) => Promise<unknown>;
     authorize?: (request: Request) => Promise<unknown> | unknown;
+    rateLimit?: RateLimitConfig;
     maxMessages?: number;
     maxMessageLength?: number;
     maxSteps?: number;

package/dist/index.js

@@ -60,12 +60,34 @@ data: ${JSON.stringify(data)}
 
 `);
 }
+function normalizeRequest(req) {
+  const rawHeaders = req.headers ?? {};
+  return {
+    ...req,
+    headers: {
+      get: (name) => {
+        const val = rawHeaders[name.toLowerCase()];
+        return Array.isArray(val) ? val[0] ?? null : val ?? null;
+      }
+    }
+  };
+}
 function createStrandHandler(config) {
   const client = new import_openai.default({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new import_core2.RateLimiter(config.rateLimit) : null;
   return async (req, res) => {
+    const normalizedReq = normalizeRequest(req);
     const body = req.body;
+    if (rateLimiter) {
+      const ip = req.ip ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        res.status(429).json({ error: "Too many requests", retryAfter: limited.retryAfter });
+        return;
+      }
+    }
     const validation = (0, import_core2.validateMessages)(body?.messages, {
       maxMessages: config.maxMessages,
       maxMessageLength: config.maxMessageLength
@@ -76,7 +98,7 @@ function createStrandHandler(config) {
     }
     if (config.authorize) {
       try {
-        await config.authorize(req);
+        await config.authorize(normalizedReq);
       } catch (err) {
         const message = err instanceof Error ? err.message : "Unauthorized";
         res.status(401).json({ error: message });
@@ -89,7 +111,7 @@ function createStrandHandler(config) {
     emit(res, "strand:start", { sessionId: (0, import_core2.generateId)(), requestId: (0, import_core2.generateId)() });
     try {
       const messages = body.messages;
-      const system = typeof config.system === "function" ? await config.system(req) : config.system ?? "";
+      const system = typeof config.system === "function" ? await config.system(normalizedReq) : config.system ?? "";
       const conversation = [
         ...system ? [{ role: "system", content: system }] : [],
         ...messages.map((m) => ({ role: m.role, content: m.content }))
@@ -154,7 +176,7 @@ function createStrandHandler(config) {
             completedTools.map(async (block) => {
               emit(res, "strand:tool-input-done", { toolCallId: block.id, input: block.input });
               try {
-                const result = await config.onToolCall?.(block.name, block.input, { request: req });
+                const result = await config.onToolCall?.(block.name, block.input, { request: normalizedReq });
                 emit(res, "strand:tool-result", { toolCallId: block.id, result });
                 return { role: "tool", tool_call_id: block.id, content: JSON.stringify(result ?? null) };
               } catch (err) {
@@ -192,7 +214,18 @@ function createStrandRoute(config) {
   const client = new import_openai2.default({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new import_core3.RateLimiter(config.rateLimit) : null;
   return async (req) => {
+    if (rateLimiter) {
+      const ip = req.headers.get("x-forwarded-for") ?? req.headers.get("x-real-ip") ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        return new Response(JSON.stringify({ error: "Too many requests", retryAfter: limited.retryAfter }), {
+          status: 429,
+          headers: { "Content-Type": "application/json", "Retry-After": String(limited.retryAfter) }
+        });
+      }
+    }
     const body = await req.json();
     const validation = (0, import_core3.validateMessages)(body?.messages, {
       maxMessages: config.maxMessages,

package/dist/index.mjs

@@ -1,6 +1,6 @@
 // src/handler.ts
 import OpenAI from "openai";
-import { generateId, validateMessages } from "@strand-js/core";
+import { generateId, validateMessages, RateLimiter } from "@strand-js/core";
 
 // src/format.ts
 import { toolToJsonSchema } from "@strand-js/core";
@@ -23,12 +23,34 @@ data: ${JSON.stringify(data)}
 
 `);
 }
+function normalizeRequest(req) {
+  const rawHeaders = req.headers ?? {};
+  return {
+    ...req,
+    headers: {
+      get: (name) => {
+        const val = rawHeaders[name.toLowerCase()];
+        return Array.isArray(val) ? val[0] ?? null : val ?? null;
+      }
+    }
+  };
+}
 function createStrandHandler(config) {
   const client = new OpenAI({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new RateLimiter(config.rateLimit) : null;
   return async (req, res) => {
+    const normalizedReq = normalizeRequest(req);
     const body = req.body;
+    if (rateLimiter) {
+      const ip = req.ip ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        res.status(429).json({ error: "Too many requests", retryAfter: limited.retryAfter });
+        return;
+      }
+    }
     const validation = validateMessages(body?.messages, {
       maxMessages: config.maxMessages,
       maxMessageLength: config.maxMessageLength
@@ -39,7 +61,7 @@ function createStrandHandler(config) {
     }
     if (config.authorize) {
       try {
-        await config.authorize(req);
+        await config.authorize(normalizedReq);
       } catch (err) {
         const message = err instanceof Error ? err.message : "Unauthorized";
         res.status(401).json({ error: message });
@@ -52,7 +74,7 @@ function createStrandHandler(config) {
     emit(res, "strand:start", { sessionId: generateId(), requestId: generateId() });
     try {
       const messages = body.messages;
-      const system = typeof config.system === "function" ? await config.system(req) : config.system ?? "";
+      const system = typeof config.system === "function" ? await config.system(normalizedReq) : config.system ?? "";
       const conversation = [
         ...system ? [{ role: "system", content: system }] : [],
         ...messages.map((m) => ({ role: m.role, content: m.content }))
@@ -117,7 +139,7 @@ function createStrandHandler(config) {
             completedTools.map(async (block) => {
               emit(res, "strand:tool-input-done", { toolCallId: block.id, input: block.input });
               try {
-                const result = await config.onToolCall?.(block.name, block.input, { request: req });
+                const result = await config.onToolCall?.(block.name, block.input, { request: normalizedReq });
                 emit(res, "strand:tool-result", { toolCallId: block.id, result });
                 return { role: "tool", tool_call_id: block.id, content: JSON.stringify(result ?? null) };
               } catch (err) {
@@ -144,7 +166,7 @@ function createStrandHandler(config) {
 
 // src/route.ts
 import OpenAI2 from "openai";
-import { generateId as generateId2, validateMessages as validateMessages2 } from "@strand-js/core";
+import { generateId as generateId2, validateMessages as validateMessages2, RateLimiter as RateLimiter2 } from "@strand-js/core";
 function sseChunk(eventType, data) {
   return new TextEncoder().encode(`event: ${eventType}
 data: ${JSON.stringify(data)}
@@ -155,7 +177,18 @@ function createStrandRoute(config) {
   const client = new OpenAI2({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new RateLimiter2(config.rateLimit) : null;
   return async (req) => {
+    if (rateLimiter) {
+      const ip = req.headers.get("x-forwarded-for") ?? req.headers.get("x-real-ip") ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        return new Response(JSON.stringify({ error: "Too many requests", retryAfter: limited.retryAfter }), {
+          status: 429,
+          headers: { "Content-Type": "application/json", "Retry-After": String(limited.retryAfter) }
+        });
+      }
+    }
     const body = await req.json();
     const validation = validateMessages2(body?.messages, {
       maxMessages: config.maxMessages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strand-js/openai",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "MIT",
   "description": "OpenAI provider adapter for Strand",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "openai": "^4.77.0",
-    "@strand-js/core": "0.1.4"
+    "@strand-js/core": "0.1.6"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",