@juspay/neurolink 13.8.14 → 13.8.15

package/docs-site/static/search-index.json

@@ -7640,7 +7640,7 @@
 {"objectID":"ad29fcad00b9d73eacff3f9ca6c0adb18b19c60ff1e6f3aa93b80e38865394a9","title":"createServer(neurolink, options?)","url":"/docs/guides/server-adapters/api-reference#createserverneurolink-options","content":"Convenience function that creates a server adapter from a NeuroLink instance.","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"createServer(neurolink, options?)","lvl3":""}},
 {"objectID":"8cc46647ccb6a0e9d912da7efa7b1827b1c6e4ef762dbb5b88baa676d6841a8a","title":"ServerAdapterFactory","url":"/docs/guides/server-adapters/api-reference#serveradapterfactory","content":"Static factory class for creating adapters. Supports dynamic imports so unused frameworks are never bundled.\n\n| Method                    | Signature                                                              | Description                       |\n| ------------------------- | ---------------------------------------------------------------------- | --------------------------------- |\n| create                  | (options: ServerAdapterFactoryOptions) => Promise<BaseServerAdapter> | Create adapter by framework name  |\n| createHono              | (neurolink, config?) => Promise<BaseServerAdapter>                   | Shortcut for Hono                 |\n| createExpress           | (neurolink, config?) => Promise<BaseServerAdapter>                   | Shortcut for Express              |\n| createFastify           | (neurolink, config?) => Promise<BaseServerAdapter>                   | Shortcut for Fastify              |\n| createKoa               | (neurolink, config?) => Promise<BaseServerAdapter>                   | Shortcut for Koa                  |\n| registerAdapter         | (framework, adapterClass) => void                                    | Register a custom adapter class   |\n| isSupported             | (framework: string) => boolean                                       | Check if a framework is supported |\n| getSupportedFrameworks  | () => Array<{framework, status, description}>                        | List all supported frameworks     |\n| getRecommendedFramework | () => ServerFramework                                                | Returns \"hono\"                  |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"ServerAdapterFactory","lvl3":""}},
 {"objectID":"84823b5000a24fb8b2d82aead2e94a037d9bdea5be7ed0587f8feb198974d1c7","title":"BaseServerAdapter","url":"/docs/guides/server-adapters/api-reference#baseserveradapter","content":"Abstract base class that all framework adapters extend. Extends EventEmitter.\n\n| Method                     | Signature                                    | Description                                   |\n| -------------------------- | -------------------------------------------- | --------------------------------------------- |\n| initialize               | () => Promise<void>                        | Initialize routes, middleware, framework      |\n| start                    | () => Promise<void>                        | Start listening (abstract)                    |\n| stop                     | () => Promise<void>                        | Stop server with graceful shutdown (abstract) |\n| registerRoute            | (route: RouteDefinition) => void           | Register a single route                       |\n| registerRouteGroup       | (group: RouteGroup) => void                | Register a route group with prefix            |\n| registerMiddleware       | (middleware: MiddlewareDefinition) => void | Register middleware                           |\n| getStatus                | () => ServerStatus                         | Get running status, uptime, route count       |\n| listRoutes               | () => RouteDefinition[]                    | List all registered routes                    |\n| getConfig                | () => RequiredServerAdapterConfig          | Get resolved configuration                    |\n| getLifecycleState        | () => ServerLifecycleState                 | Get current lifecycle state                   |\n| getActiveConnectionCount | () => number                               | Number of active connections                  |\n| getFrameworkInstance     | () => unknown                              | Get underlying framework instance (abstract)  |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"BaseServerAdapter","lvl3":""}},
-{"objectID":"8147853e8b9b9e7fc31c0480161f56665f741cd53ccbeb50aeed5c67242ed3b3","title":"ServerAdapterConfig","url":"/docs/guides/server-adapters/api-reference#serveradapterconfig","content":"All fields are optional; defaults are applied by the base class.\n\n| Field                  | Type               | Default                  | Description                       |\n| ---------------------- | ------------------ | ------------------------ | --------------------------------- |\n| port                 | number           | 3000                   | Server port                       |\n| host                 | string           | \"0.0.0.0\"              | Server host                       |\n| basePath             | string           | \"/api\"                 | Base path for all routes          |\n| cors                 | CORSConfig       | enabled, origins [\"*\"] | CORS settings                     |\n| rateLimit            | RateLimitConfig  | enabled, 100 req/15 min  | Rate limiting                     |\n| bodyParser           | BodyParserConfig | enabled, 10 MB limit     | Body parsing                      |\n| logging              | LoggingConfig    | enabled, level \"info\"  | Request logging                   |\n| timeout              | number           | 30000                  | Request timeout (ms)              |\n| enableMetrics        | boolean          | true                   | Expose /api/metrics             |\n| enableSwagger        | boolean          | false                  | Enable OpenAPI docs               |\n| disableBuiltInHealth | boolean          | false                  | Skip built-in /health, /ready |\n| redaction            | RedactionConfig  | disabled                 | Stream redaction settings         |\n| shutdown             | ShutdownConfig   | 30s shutdown, 15s drain  | Graceful shutdown behavior        |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"ServerAdapterConfig","lvl3":""}},
+{"objectID":"8147853e8b9b9e7fc31c0480161f56665f741cd53ccbeb50aeed5c67242ed3b3","title":"ServerAdapterConfig","url":"/docs/guides/server-adapters/api-reference#serveradapterconfig","content":"All fields are optional; defaults are applied by the base class.\n\n| Field                  | Type               | Default                  | Description                       |\n| ---------------------- | ------------------ | ------------------------ | --------------------------------- |\n| port                 | number           | 3000                   | Server port                       |\n| host                 | string           | \"0.0.0.0\"              | Server host                       |\n| basePath             | string           | \"/api\"                 | Base path for all routes          |\n| cors                 | CORSConfig       | enabled, origins [\"*\"] | CORS settings                     |\n| rateLimit            | RateLimitConfig  | enabled, 100 req/15 min  | Rate limiting                     |\n| bodyParser           | BodyParserConfig | enabled, 10 MB limit     | Body parsing                      |\n| logging              | LoggingConfig    | enabled, level \"info\"  | Request logging                   |\n| timeout              | number           | 30000                  | Request timeout (ms)              |\n| enableMetrics        | boolean          | true                   | Expose /api/metrics             |\n| enableSwagger        | boolean          | false                  | Enable OpenAPI docs               |\n| disableBuiltInHealth | boolean          | false                  | Skip built-in /health, /ready |\n| redaction            | RedactionConfig  | disabled                 | Stream redaction settings         |\n| shutdown             | ShutdownConfig   | 30s shutdown, 15s drain  | Graceful shutdown behavior        |\n| carryMiddlewareState | boolean          | false                  | Carry middleware state (opt-in)   |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"ServerAdapterConfig","lvl3":""}},
 {"objectID":"b9b51bfed21ee76f61c6b63bb94df2c91a354520e27a7b4bd1a18092fd42fe93","title":"ShutdownConfig","url":"/docs/guides/server-adapters/api-reference#shutdownconfig","content":"| Field                       | Type      | Default | Description                   |\n| --------------------------- | --------- | ------- | ----------------------------- |\n| gracefulShutdownTimeoutMs | number  | 30000 | Max time for entire shutdown  |\n| drainTimeoutMs            | number  | 15000 | Max time to drain connections |\n| forceClose                | boolean | true  | Force-close after timeout     |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"ShutdownConfig","lvl3":""}},
 {"objectID":"20dfcebcadaaeeffe2c27254dd2d227fabc2307718987ac56dba6ec74ce8deaa","title":"Server Lifecycle States","url":"/docs/guides/server-adapters/api-reference#server-lifecycle-states","content":"\"uninitialized\" | \"initializing\" | \"initialized\" | \"starting\" | \"running\" | \"draining\" | \"stopping\" | \"stopped\" | \"error\"","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"Server Lifecycle States","lvl3":""}},
 {"objectID":"b4f54c24b5274a577a9050cb268ff0e8254297ba5f2c865ca5343f9b8d9b2ca9","title":"Events (ServerAdapterEvents)","url":"/docs/guides/server-adapters/api-reference#events-serveradapterevents","content":"| Event         | Payload                                          |\n| ------------- | ------------------------------------------------ |\n| initialized | { config, routeCount, middlewareCount }        |\n| started     | { port, host, timestamp }                      |\n| stopped     | { uptime, timestamp }                          |\n| request     | { requestId, method, path, timestamp }         |\n| response    | { requestId, statusCode, duration, timestamp } |\n| error       | { requestId?, error, timestamp }               |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"Events (ServerAdapterEvents)","lvl3":""}},
@@ -7719,7 +7719,7 @@
 {"objectID":"1aba31d0169a6255c13c0834ddf34f5e433ad08bd11d3f4f8d77e52d2aac5178","title":"Route and Middleware Types","url":"/docs/guides/server-adapters/api-reference#route-and-middleware-types","content":"| Type                   | Description                                                                         |\n| ---------------------- | ----------------------------------------------------------------------------------- |\n| HttpMethod           | \"GET\" \\| \"POST\" \\| \"PUT\" \\| \"DELETE\" \\| \"PATCH\" \\| \"OPTIONS\"                      |\n| RouteDefinition      | Full route definition                                                               |\n| RouteGroup           | Group of routes with prefix and optional middleware                                 |\n| RouteHandler<T>      | (ctx: ServerContext) => Promise<T \\| ServerResponse<T> \\| AsyncIterable<unknown>> |\n| MiddlewareDefinition | Middleware definition with name, order, handler, paths                              |\n| MiddlewareHandler    | (ctx, next) => Promise<unknown>                                                   |\n| CreateRoutesOptions  | Options for createAllRoutes                                                       |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"Route and Middleware Types","lvl3":""}},
 {"objectID":"a4daff1325a8b89a05cc217c671de5a359fdcd820d52991fdedf7265940eb257","title":"Factory Types","url":"/docs/guides/server-adapters/api-reference#factory-types","content":"| Type                          | Description                                 |\n| ----------------------------- | ------------------------------------------- |\n| ServerFramework             | \"hono\" \\| \"express\" \\| \"fastify\" \\| \"koa\" |\n| ServerAdapterFactoryOptions | { framework, neurolink, config? }         |\n| ServerStatus                | Server status snapshot                      |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"Factory Types","lvl3":""}},
 {"objectID":"4f2b202faec0c6c8bdbf6913438e0809776d019ac03be6082db1cd3a6cc9cc20","title":"Streaming Types","url":"/docs/guides/server-adapters/api-reference#streaming-types","content":"| Type                                                 | Description                       |\n| ---------------------------------------------------- | --------------------------------- |\n| DataStreamWriter                                   | Writer interface for data streams |\n| DataStreamEventType                                | Event type union                  |\n| DataStreamEvent                                    | Base event                        |\n| TextStartEvent / TextDeltaEvent / TextEndEvent | Text streaming events             |\n| ToolCallEvent / ToolResultEvent                  | Tool events                       |\n| DataEvent / ErrorEvent / FinishEvent           | Utility events                    |\n| DataStreamWriterConfig                             | Writer factory config             |\n| DataStreamResponseConfig                           | Response factory config           |\n| SSEEventOptions                                    | SSE formatting options            |\n| SSEWriteOptions                                    | SSE write options                 |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"Streaming Types","lvl3":""}},
-{"objectID":"f3b123615ba16d79e4f558be441599b7fa3adb19657e4f75e3035e79ba7c936a","title":"WebSocket Types","url":"/docs/guides/server-adapters/api-reference#websocket-types","content":"| Type                   | Description                                                           |\n| ---------------------- | --------------------------------------------------------------------- |\n| WebSocketConfig      | WebSocket server settings                                             |\n| WebSocketConnection  | Connection object                                                     |\n| WebSocketHandler     | Event handler interface (onOpen, onMessage, onClose, onError) |\n| WebSocketMessage     | Message object                                                        |\n| WebSocketMessageType | \"text\" \\| \"binary\" \\| \"ping\" \\| \"pong\" \\| \"close\"                   |\n| WebSocketAuthConfig  | Auth config for WebSocket (same shape as AuthConfig from types)     |\n| AuthenticatedUser    | User object with id, email, name, roles, permissions, metadata        |\n| AuthStrategy         | \"bearer\" \\| \"apiKey\" \\| \"basic\" \\| \"custom\" \\| \"none\"               |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"WebSocket Types","lvl3":""}},
+{"objectID":"f3b123615ba16d79e4f558be441599b7fa3adb19657e4f75e3035e79ba7c936a","title":"WebSocket Types","url":"/docs/guides/server-adapters/api-reference#websocket-types","content":"| Type                   | Description                                                           |\n| ---------------------- | --------------------------------------------------------------------- |\n| WebSocketConfig      | WebSocket server settings                                             |\n| WebSocketConnection  | Connection object                                                     |\n| WebSocketHandler     | Event handler interface (onOpen, onMessage, onClose, onError) |\n| WebSocketMessage     | Message object                                                        |\n| WebSocketMessageType | \"text\" \\| \"binary\" \\| \"ping\" \\| \"pong\" \\| \"close\"                   |\n| WebSocketAuthConfig  | Auth config for WebSocket (same shape as AuthConfig from types)     |\n| AuthenticatedUser    | User object: id, shared, email, name, roles, permissions, metadata    |\n| AuthStrategy         | \"bearer\" \\| \"apiKey\" \\| \"basic\" \\| \"custom\" \\| \"none\"               |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"WebSocket Types","lvl3":""}},
 {"objectID":"75ac5dd684dae3c078a954801e7d8c39e4a7ab6eefb4c4e13140af491da67cd3","title":"Error Types","url":"/docs/guides/server-adapters/api-reference#error-types","content":"| Type                         | Description                           |\n| ---------------------------- | ------------------------------------- |\n| ErrorCategoryType          | Error category union                  |\n| ErrorSeverityType          | Error severity union                  |\n| ServerAdapterErrorCodeType | Error code union                      |\n| ServerAdapterErrorContext  | Context object for error construction |","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"Error Types","lvl3":""}},
 {"objectID":"9930ededc5ccfc16a496b95cde993bfd1fdff5dae26b819e6e6a7b11de933418","title":"ErrorCategory","url":"/docs/guides/server-adapters/api-reference#errorcategory","content":"ErrorCategory","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"ErrorCategory","lvl3":""}},
 {"objectID":"81be0bf7c25a87d9ade845c9461d764b1851de541c9182f00c87b86d6d98e4d2","title":"ErrorSeverity","url":"/docs/guides/server-adapters/api-reference#errorseverity","content":"ErrorSeverity","hierarchy":{"lvl0":"Guides","lvl1":"Server Adapters API Reference","lvl2":"ErrorSeverity","lvl3":""}},
@@ -7993,7 +7993,7 @@
 {"objectID":"20b4b9bfe4f6987d7c88692d17430396985fe8533056d76bd16efcc0af7c8e74","title":"Custom Rate Limit Store (Redis)","url":"/docs/guides/server-adapters/middleware#custom-rate-limit-store-redis","content":"Custom Rate Limit Store (Redis)","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Custom Rate Limit Store (Redis)","lvl3":""}},
 {"objectID":"7826f375db586c8004183275c0715b410e96f673701874419ba565b6ff3dd214","title":"When to Use","url":"/docs/guides/server-adapters/middleware#when-to-use-9","content":"API abuse prevention\nFair usage enforcement\nCost control for expensive operations\nProtection against DDoS attacks","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"When to Use","lvl3":""}},
 {"objectID":"ce6af8a97b716420a9742ad3d965d5cb0aa5912e3d52d961814c83e9e1abaa19","title":"Authentication Middleware","url":"/docs/guides/server-adapters/middleware#authentication-middleware","content":"Provides flexible authentication support with multiple strategies.","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Authentication Middleware","lvl3":""}},
-{"objectID":"39ede52482e2c4efd166bd94c8fa1ea4a6957b2528e2bca5c058208e4f293b81","title":"Configuration","url":"/docs/guides/server-adapters/middleware#configuration-8","content":"Configuration","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Configuration","lvl3":""}},
+{"objectID":"39ede52482e2c4efd166bd94c8fa1ea4a6957b2528e2bca5c058208e4f293b81","title":"Configuration","url":"/docs/guides/server-adapters/middleware#configuration-8","content":"The authenticated user is set on ctx.user. On the built-in adapters (Hono,\nExpress, Fastify and Koa) it reaches later middleware and the route handler on\nevery request only when the server is created with carryMiddlewareState: true.\nBy default Express, Fastify and Koa, and Hono when the client sent no\nX-Request-ID of its own, hand each middleware step and the handler a fresh\ncontext, so a role guard registered after authentication refuses everyone there;\nonly Hono with a client X-Request-ID shares the context. The option does not\napply to a context you build yourself: a custom adapter, or a route handler you\ncall directly, can supply a context that already has ctx.user set. See\nCarrying middleware state\nin the security guide. Whether the agent routes treat ctx.user as the caller is\na separate choice: see perUserAuth in the\nsecurity guide.","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Configuration","lvl3":""}},
 {"objectID":"51fb1cc8c6e28634044df5ad09ea7250e2d1520cade26f2996bf81c174b30aa9","title":"Usage","url":"/docs/guides/server-adapters/middleware#usage-10","content":"Usage","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Usage","lvl3":""}},
 {"objectID":"dc019f0ad08d89054d4f68945d6855bbc6d74da0b3f8082e35f56fa5f731ec51","title":"Headers Read","url":"/docs/guides/server-adapters/middleware#headers-read","content":"| Header          | Auth Type     | Description                          |\n| --------------- | ------------- | ------------------------------------ |\n| Authorization | bearer, basic | Bearer <token> or Basic <base64> |\n| X-API-Key     | api-key       | Raw API key value                    |","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Headers Read","lvl3":""}},
 {"objectID":"43776c9da774387f221eb7918931d5a4a59b42c949ef248c30c7afb5512ee7ea","title":"Dev Playground Support","url":"/docs/guides/server-adapters/middleware#dev-playground-support","content":"Requests with an X-NeuroLink-Dev-Playground: true (or X-NeuroLink-Playground: true) header bypass authentication and receive a default developer user context (id: \"playground\", roles: [\"developer\"]), but only when NODE_ENV is exactly development. The variable is read on every request.\n\nWith NODE_ENV unset, production, test, staging or any other value, the header is ignored and the request must carry a valid credential. The bypass is therefore off by default in a deployment that never sets NODE_ENV. Pass skipDevPlayground: false to refuse the header even in development.","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Dev Playground Support","lvl3":""}},
@@ -8011,13 +8011,15 @@
 {"objectID":"75f9986be54ffb5b39930d9b1514e6a696e982fe41bbc2a600033e3254bad57b","title":"When to Use","url":"/docs/guides/server-adapters/middleware#when-to-use-12","content":"Expensive operations (database queries, AI generation)\nFrequently requested static data\nRate limit budget optimization\nReducing latency for repeated requests","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"When to Use","lvl3":""}},
 {"objectID":"3e522465420d38d5c0e20166dfc374452a7c8366d592ff2cf3a9cb9afadc3b7d","title":"Composing Middleware","url":"/docs/guides/server-adapters/middleware#composing-middleware","content":"Middleware are executed in order based on their order property. Here's a recommended production setup:","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Composing Middleware","lvl3":""}},
 {"objectID":"293ec2d6d2933e2f370ee73b87ee9684f64143acd21d8bbb5e7e48640ec0d2bb","title":"Next Steps","url":"/docs/guides/server-adapters/middleware#next-steps","content":"Configuration Reference - Full server configuration options\nSecurity Best Practices - Authentication and authorization patterns\nDeployment Guide - Production deployment strategies\nExpress Adapter - Express-specific middleware integration\nFastify Adapter - Fastify-specific hooks and plugins","hierarchy":{"lvl0":"Guides","lvl1":"Middleware Reference","lvl2":"Next Steps","lvl3":""}},
-{"objectID":"3f8ed2c1cc0b9c59fe231fb08fe10302270284784b912664350299fe0a5de458","title":"Security Best Practices","url":"/docs/guides/server-adapters/security","content":"Security Best Practices\n\nProtect your AI APIs with comprehensive security measures\n\nThis guide covers authentication, authorization, rate limiting, and other security best practices for deploying NeuroLink server adapters in production.\n\nAuthentication\n\nNeuroLink server adapters support multiple authentication strategies out of the box.\n\nBearer Token Authentication\n\nBearer tokens (JWT, OAuth tokens) are the most common authentication method for APIs:\n\nAPI Key Authentication\n\nFor service-to-service communication or simple API access:\n\nBasic Authentication\n\nFor simple username/password authentication:\n\nCustom Authentication\n\nFor OAuth 2.0, OIDC, or custom schemes:\n\nSkip Paths Configuration\n\nCertain endpoints should bypass authentication:\n\nRate Limiting\n\nProtect your API from abuse with configurable rate limiting.\n\nBasic Configuration\n\nPer-IP Rate Limiting\n\nThe default behavior limits requests by client IP:\n\nPer-User Rate Limiting\n\nLimit based on authenticated user:\n\nPer-API-Key Rate Limiting\n\nDifferent limits for different API keys:\n\nSliding Window Rate Limiting\n\nFor smoother rate limiting that prevents burst-and-wait patterns:\n\nRate Limit Headers\n\nRate limit middleware automatically adds headers to responses:\n\nRate Limit Response Headers\n\nWhen a request exceeds the rate limit, the server returns HTTP 429 (Too Many Requests) with these headers:\n\n| Header                  | Description                      | Example      |\n| ----------------------- | -------------------------------- | ------------ |\n| X-RateLimit-Limit     | Maximum requests per window      | 100        |\n| X-RateLimit-Remaining | Requests remaining in window     | 0          |\n| X-RateLimit-Reset     | Unix timestamp when limit resets | 1706745660 |\n| Retry-After           | Seconds to wait before retrying  | 60         |\n\nClients should respect the Retry-After header to avoid unnecessary requests.\n\nStream Redaction\n\nProtect sensitive data in streaming responses. Redaction is disabled by default and must be explicitly enabled.\n\nWhy Disabled by Default?\n\nStream redaction is disabled by default because:\nIt adds processing overhead to every stream chunk\nDevelopers should consciously decide what to redact\nOverly aggressive redaction can break functionality\n\nEnabling Stream Redaction\n\nCustom Redaction Configuration\n\nProgrammatic Redaction\n\nFor custom streaming routes:\n\nCORS Configuration\n\nProperly configure Cross-Origin Resource Sharing:\n\nDynamic CORS Origins\n\nFor multi-tenant applications:\n\nSecurity Headers\n\nAdd essential security headers to all responses. NeuroLink provides a built-in createSecurityHeadersMiddleware that works with all server adapters (Hono, Express, Fastify, Koa).\n\nUsing NeuroLink Security Headers Middleware (All Adapters)\n\nThe recommended approach is to use NeuroLink's built-in security headers middleware, which works consistently across all frameworks:\n\nConfiguration Options\n\n| Option                  | Type                              | Default                             | Description                    |\n| ----------------------- | --------------------------------- | ----------------------------------- | ------------------------------ |\n| contentSecurityPolicy | string                          | undefined                         | Content-Security-Policy header |\n| frameOptions          | \"DENY\" \\| \"SAMEORIGIN\" \\| false | \"DENY\"                            | X-Frame-Options header         |\n| contentTypeOptions    | \"nosniff\" \\| false              | \"nosniff\"                         | X-Content-Type-Options header  |\n| hstsMaxAge            | number \\| false                 | 31536000 (1 year)                 | HSTS max-age in seconds        |\n| referrerPolicy        | string \\| false                 | \"strict-origin-when-cross-origin\" | Referrer-Policy header         |\n| customHeaders         | Record<string, string>          | {}                                | Additional custom headers      |\n\nHeaders Set by the Middleware\n\nThe middleware automatically sets these security headers:\n\n| Header                      | Default Value                         | Purpose                       |\n| --------------------------- | ------------------------------------- | ----------------------------- |\n| X-Frame-Options           | DENY                                | Prevents clickjacking attacks |\n| X-Content-Type-Options    | nosniff                             | Prevents MIME type sniffing   |\n| Strict-Transport-Security | max-age=31536000; includeSubDomains | Enforces HTTPS connections    |\n| Referrer-Policy           | strict-origin-when-cross-origin     | Controls referrer information |\n| X-XSS-Protection          | 1; mode=block                       | XSS filter for older browsers |\n| Content-Security-Policy   | (only if configured)                  | Controls resource loading     |\n\nExpress Example\n\nFastify Example\n\nKoa Example\n\nHono Example\n\nDisabling Specific Headers\n\nSet any option to false to disable that header:\n\nFramew","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"","lvl3":""}},
+{"objectID":"3f8ed2c1cc0b9c59fe231fb08fe10302270284784b912664350299fe0a5de458","title":"Security Best Practices","url":"/docs/guides/server-adapters/security","content":"Security Best Practices\n\nProtect your AI APIs with comprehensive security measures\n\nThis guide covers authentication, authorization, rate limiting, and other security best practices for deploying NeuroLink server adapters in production.\n\nAuthentication\n\nNeuroLink server adapters support multiple authentication strategies out of the box.\n\nBearer Token Authentication\n\nBearer tokens (JWT, OAuth tokens) are the most common authentication method for APIs:\n\nAPI Key Authentication\n\nFor service-to-service communication or simple API access:\n\nBasic Authentication\n\nFor simple username/password authentication:\n\nCustom Authentication\n\nFor OAuth 2.0, OIDC, or custom schemes:\n\nCarrying middleware state to guards and handlers (carryMiddlewareState)\n\nAuthentication middleware sets ctx.user. On the built-in adapters, whether the\nmiddleware that runs after it, and the route handler, see it depends on the\nadapter and on carryMiddlewareState, which is off by default: each adapter\nthen propagates context as it always did. Express, Fastify and Koa build a fresh\ncontext for every middleware step and for the handler and carry only the\nresponse headers; Hono shares one context between the steps and the handler only\nwhen the client sent its own X-Request-ID.\n\nThe option does not apply to a context you build yourself: a custom adapter, or a\nroute handler you call directly, can supply a context that already has ctx.user\nset.\n\nSo by default a role guard (createRoleMiddleware) registered after\ncreateAuthMiddleware sees the user on one request shape only. Measured: it\nanswers 401 to every request on Express, Fastify and Koa, and on Hono without a\nclient X-Request-ID, even for a user holding the required role, and a\nrate-limit keyGenerator reads ctx.user as undefined there. Set the option on\nthe server to carry ctx.user, ctx.session, ctx.metadata and the abort\nsignal to later middleware and the handler on every built-in adapter:\n\nWith it on, the role guard admits a user holding the role (200) and refuses one\nwithout it (403), and a keyGenerator sees ctx.user, on every built-in adapter. A key\ngenerator that keys on the user id then does what it says, so make it ignore a\nshared identity (ctx.user.shared), or every holder of one API key falls into a\nsingle bucket; the rate-limit examples below do. Turning the option on does not\nchange whose identity the agent routes trust, and registerAllRoutes turns it\non by itself when given perUserAuth, as the next section says.\n\nWho the agent routes treat as the user (perUserAuth)\n\nWhether the agent routes (/agent/execute, /agent/stream, and the skill\nmutation routes' requestedBy) trust ctx.user as a person is a separate\nchoice from whether the server carries it: a single shared API key sets the same\nctx.user for every caller, and taking it as the user would give every client\none userId and no conversation memory.\n\nSo without an opt-in the agent routes resolve identity as they always have:\nOn Express, Fastify and Koa, and on Hono when the client sent no\n  X-Request-ID, userId and sessionId come from the request body.\n  ctx.user and ctx.session are ignored (they are not in the handler's\n  context at all unless the server carries middleware state), and the skill\n  routes use the body's requestedBy.\nOn Hono, when the client sent its own X-Request-ID header, an authenticated\n  ctx.user wins over the body (and ctx.session over the body's\n  sessionId), as it did before. Hono kept the middleware's context under that\n  header, so the handler found it. That is the only built-in combination where\n  the default ever guarded userId.\nA context the built-in adapters did not hand the carry to keeps the same\n  rule, an authenticated ctx.user wins: an adapter you wrote that sets\n  ctx.user itself, or a route handler you call directly with a context you\n  built (a test harness, for one).\n\nSet perUserAuth: true when your middleware identifies individual people (one\ncredential per person). Only this option, with carryMiddlewareState on, makes the agent routes take\nthe user from ctx.user, and ignore the body's userId, on every built-in\nadapter and for every request:\n\nregisterAllRoutes also turns on carryMiddlewareState for the server, because\nthe routes can only take identity from ctx.user if the adapter hands it to the\nhandler. With carryMiddlewareState on, a perUserAuth request that your middleware\nauthenticated reaches the handler with that user on every built-in adapter. A\nrequest that no middleware authenticated (optional authentication) runs as\nanonymous, with no userId and no session.\n\nIf you register the agent routes yourself with\ncreateAgentRoutes(\"/api\", { perUserAuth: true }), create the server with\ncarryMiddlewareState: true. Without it, whether a perUserAuth request has a\nuser depends on the adapter and the request:\nHono, when the client sent its own X-Request-ID header: an authenticated\n  request has its user and session. Hono hands the handler the middleware's context for such\n  a request whether or not carryM","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"","lvl3":""}},
 {"objectID":"7cdb3cd74c088f4b197de4db297c2eb3b47c353b41ce1a84ed2e12548147b408","title":"Security Best Practices","url":"/docs/guides/server-adapters/security#security-best-practices","content":"Protect your AI APIs with comprehensive security measures\n\nThis guide covers authentication, authorization, rate limiting, and other security best practices for deploying NeuroLink server adapters in production.","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Security Best Practices","lvl3":""}},
 {"objectID":"7165b0d19a27c31d8ca81ea15e5a79ad56fd20234c80f3c955a1c579a669e84f","title":"Authentication","url":"/docs/guides/server-adapters/security#authentication","content":"NeuroLink server adapters support multiple authentication strategies out of the box.","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Authentication","lvl3":""}},
 {"objectID":"9b83e309c15f0ef505257e6ef1750da7d26183f6b598bcd24996ad199df910cc","title":"Bearer Token Authentication","url":"/docs/guides/server-adapters/security#bearer-token-authentication","content":"Bearer tokens (JWT, OAuth tokens) are the most common authentication method for APIs:","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Bearer Token Authentication","lvl3":""}},
 {"objectID":"9447de8730cba3e8d7100e35f3edc53f5d838fed4aab12473ba0d154a63ee127","title":"API Key Authentication","url":"/docs/guides/server-adapters/security#api-key-authentication","content":"For service-to-service communication or simple API access:","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"API Key Authentication","lvl3":""}},
 {"objectID":"55486c9aed152083800f7142accdefaf2750be560161e53b51e4e7f076e78783","title":"Basic Authentication","url":"/docs/guides/server-adapters/security#basic-authentication","content":"For simple username/password authentication:","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Basic Authentication","lvl3":""}},
 {"objectID":"3975b5affef7749530f0c88db91dccfe9ae500ea616d9ae756de09c501e74e09","title":"Custom Authentication","url":"/docs/guides/server-adapters/security#custom-authentication","content":"For OAuth 2.0, OIDC, or custom schemes:","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Custom Authentication","lvl3":""}},
+{"objectID":"6c5ba88d8c7484db5bcd476fabfca5763fad609f689edee826a37f9360219610","title":"Carrying middleware state to guards and handlers (carryMiddlewareState)","url":"/docs/guides/server-adapters/security#carrying-middleware-state-to-guards-and-handlers-carrymiddlewarestate","content":"Authentication middleware sets ctx.user. On the built-in adapters, whether the\nmiddleware that runs after it, and the route handler, see it depends on the\nadapter and on carryMiddlewareState, which is off by default: each adapter\nthen propagates context as it always did. Express, Fastify and Koa build a fresh\ncontext for every middleware step and for the handler and carry only the\nresponse headers; Hono shares one context between the steps and the handler only\nwhen the client sent its own X-Request-ID.\n\nThe option does not apply to a context you build yourself: a custom adapter, or a\nroute handler you call directly, can supply a context that already has ctx.user\nset.\n\nSo by default a role guard (createRoleMiddleware) registered after\ncreateAuthMiddleware sees the user on one request shape only. Measured: it\nanswers 401 to every request on Express, Fastify and Koa, and on Hono without a\nclient X-Request-ID, even for a user holding the required role, and a\nrate-limit keyGenerator reads ctx.user as undefined there. Set the option on\nthe server to carry ctx.user, ctx.session, ctx.metadata and the abort\nsignal to later middleware and the handler on every built-in adapter:\n\nWith it on, the role guard admits a user holding the role (200) and refuses one\nwithout it (403), and a keyGenerator sees ctx.user, on every built-in adapter. A key\ngenerator that keys on the user id then does what it says, so make it ignore a\nshared identity (ctx.user.shared), or every holder of one API key falls into a\nsingle bucket; the rate-limit examples below do. Turning the option on does not\nchange whose identity the agent routes trust, and registerAllRoutes turns it\non by itself when given perUserAuth, as the next section says.","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Carrying middleware state to guards and handlers (carryMiddlewareState)","lvl3":""}},
+{"objectID":"f4407e53fe643ff19343687ebdafae3eaf56adc6a7cafc61834a490cc90bffd1","title":"Who the agent routes treat as the user (perUserAuth)","url":"/docs/guides/server-adapters/security#who-the-agent-routes-treat-as-the-user-peruserauth","content":"Whether the agent routes (/agent/execute, /agent/stream, and the skill\nmutation routes' requestedBy) trust ctx.user as a person is a separate\nchoice from whether the server carries it: a single shared API key sets the same\nctx.user for every caller, and taking it as the user would give every client\none userId and no conversation memory.\n\nSo without an opt-in the agent routes resolve identity as they always have:\nOn Express, Fastify and Koa, and on Hono when the client sent no\n  X-Request-ID, userId and sessionId come from the request body.\n  ctx.user and ctx.session are ignored (they are not in the handler's\n  context at all unless the server carries middleware state), and the skill\n  routes use the body's requestedBy.\nOn Hono, when the client sent its own X-Request-ID header, an authenticated\n  ctx.user wins over the body (and ctx.session over the body's\n  sessionId), as it did before. Hono kept the middleware's context under that\n  header, so the handler found it. That is the only built-in combination where\n  the default ever guarded userId.\nA context the built-in adapters did not hand the carry to keeps the same\n  rule, an authenticated ctx.user wins: an adapter you wrote that sets\n  ctx.user itself, or a route handler you call directly with a context you\n  built (a test harness, for one).\n\nSet perUserAuth: true when your middleware identifies individual people (one\ncredential per person). Only this option, with carryMiddlewareState on, makes the agent routes take\nthe user from ctx.user, and ignore the body's userId, on every built-in\nadapter and for every request:\n\nregisterAllRoutes also turns on carryMiddlewareState for the server, because\nthe routes can only take identity from ctx.user if the adapter hands it to the\nhandler. With carryMiddlewareState on, a perUserAuth request that your middleware\nauthenticated reaches the handler with that user on every built-in adapter.","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Who the agent routes treat as the user (perUserAuth)","lvl3":""}},
 {"objectID":"0eb6912fafa8a4ab0aa683215da36521df010f267a7e6fa07e5b36117285fbd7","title":"Skip Paths Configuration","url":"/docs/guides/server-adapters/security#skip-paths-configuration","content":"Certain endpoints should bypass authentication:","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Skip Paths Configuration","lvl3":""}},
 {"objectID":"9e51a77be4d03e43ee3f36b8d0011c07bc65e43fe63401529fc309117cc8f14d","title":"Rate Limiting","url":"/docs/guides/server-adapters/security#rate-limiting","content":"Protect your API from abuse with configurable rate limiting.","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Rate Limiting","lvl3":""}},
 {"objectID":"c6e767ba1ce5b5628ab9d303d199a6fb4947a70e2e43358a5d7f89a96534c74e","title":"Basic Configuration","url":"/docs/guides/server-adapters/security#basic-configuration","content":"Basic Configuration","hierarchy":{"lvl0":"Guides","lvl1":"Security Best Practices","lvl2":"Basic Configuration","lvl3":""}},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "13.8.14",
+  "version": "13.8.15",
   "packageManager": "pnpm@10.28.2",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {
@@ -214,6 +214,7 @@
     "test:server-boundaries": "pnpm exec tsx test/continuous-test-suite-server-boundaries.ts",
     "test:agent-input-guard": "pnpm exec tsx test/continuous-test-suite-agent-input-guard.ts",
     "test:body-limits": "pnpm exec tsx test/continuous-test-suite-body-limits.ts",
+    "test:adapter-request-context": "pnpm exec tsx test/continuous-test-suite-adapter-request-context.ts",
     "test:websocket-agent-handler": "pnpm exec tsx test/continuous-test-suite-websocket-agent-handler.ts",
     "test:tool-reliability": "pnpm exec tsx test/continuous-test-suite-tool-reliability.ts",
     "test:video-abort": "pnpm exec tsx test/continuous-test-suite-video-abort.ts",