@strand-js/anthropic 0.1.4 → 0.1.6

package/README.md

@@ -54,17 +54,74 @@ createStrandHandler({
 })
 ```
 
-### With auth
+## Production security checklist
+
+Before going live, configure these options:
 
 ```ts
 createStrandHandler({
   apiKey: process.env.ANTHROPIC_API_KEY,
   model: 'claude-sonnet-4-6',
+
+  // 1. REQUIRED: authenticate every request
+  // Without this, anyone can hit your endpoint and burn your API credits.
   authorize: async (request) => {
-    const user = await verifyToken(request.headers.get('authorization'))
-    if (!user) throw new Error('Unauthorized')
+    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
+  // Prevents a single user from spamming your endpoint.
+  rateLimit: {
+    windowMs: 60_000,   // 1 minute window
+    maxRequests: 20,    // max 20 requests per IP per minute
   },
+
+  // 3. RECOMMENDED: limit message size
+  // Prevents oversized payloads from reaching the LLM.
+  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` is a function you provide that runs before any LLM call. Strand calls it with the incoming request. If it throws, the request is rejected with a 401 and no API credits are used. If it resolves, the request continues.
+
+```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')
+}
+
+// Simple shared secret example
+authorize: async (request) => {
+  if (request.headers.get('x-api-key') !== process.env.MY_SECRET)
+    throw new Error('Unauthorized')
+}
+```
+
+## Config reference
+
+| Option | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | Your Anthropic API key |
+| `model` | `string` | Model ID, e.g. `'claude-sonnet-4-6'` |
+| `system` | `string \| (req) => string` | System prompt (static or dynamic) |
+| `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) |
+| `onFinish` | `(session) => void` | Called after response completes |
+
 [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

@@ -57,12 +57,38 @@ data: ${JSON.stringify(data)}
 
 `);
 }
+function normalizeRequest(req) {
+  const rawHeaders = req.headers ?? {};
+  const normalized = {
+    ...req,
+    headers: {
+      get: (name) => {
+        const val = rawHeaders[name.toLowerCase()];
+        return Array.isArray(val) ? val[0] ?? null : val ?? null;
+      }
+    }
+  };
+  return normalized;
+}
 function createStrandHandler(config) {
   const client = new import_sdk.default({ apiKey: config.apiKey });
   const anthropicTools = (config.tools ?? []).map(toolToAnthropicTool);
   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
@@ -73,7 +99,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 });
@@ -86,7 +112,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 = messages.map((m) => ({
         role: m.role,
         content: m.content
@@ -152,7 +178,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 { type: "tool_result", tool_use_id: block.id, content: JSON.stringify(result ?? null) };
               } catch (err) {
@@ -190,7 +216,18 @@ function createStrandRoute(config) {
   const client = new import_sdk2.default({ apiKey: config.apiKey });
   const anthropicTools = (config.tools ?? []).map(toolToAnthropicTool);
   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 Anthropic from "@anthropic-ai/sdk";
-import { generateId, validateMessages } from "@strand-js/core";
+import { generateId, validateMessages, RateLimiter } from "@strand-js/core";
 
 // src/format.ts
 import { toolToJsonSchema } from "@strand-js/core";
@@ -20,12 +20,38 @@ data: ${JSON.stringify(data)}
 
 `);
 }
+function normalizeRequest(req) {
+  const rawHeaders = req.headers ?? {};
+  const normalized = {
+    ...req,
+    headers: {
+      get: (name) => {
+        const val = rawHeaders[name.toLowerCase()];
+        return Array.isArray(val) ? val[0] ?? null : val ?? null;
+      }
+    }
+  };
+  return normalized;
+}
 function createStrandHandler(config) {
   const client = new Anthropic({ apiKey: config.apiKey });
   const anthropicTools = (config.tools ?? []).map(toolToAnthropicTool);
   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
@@ -36,7 +62,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 });
@@ -49,7 +75,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 = messages.map((m) => ({
         role: m.role,
         content: m.content
@@ -115,7 +141,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 { type: "tool_result", tool_use_id: block.id, content: JSON.stringify(result ?? null) };
               } catch (err) {
@@ -142,7 +168,7 @@ function createStrandHandler(config) {
 
 // src/route.ts
 import Anthropic2 from "@anthropic-ai/sdk";
-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)}
@@ -153,7 +179,18 @@ function createStrandRoute(config) {
   const client = new Anthropic2({ apiKey: config.apiKey });
   const anthropicTools = (config.tools ?? []).map(toolToAnthropicTool);
   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/anthropic",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "MIT",
   "description": "Anthropic provider adapter for Strand",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@anthropic-ai/sdk": "^0.40.0",
-    "@strand-js/core": "0.1.4"
+    "@strand-js/core": "0.1.6"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",