@juspay/neurolink 9.54.6 → 9.54.8

package/dist/lib/auth/errors.d.ts

@@ -55,7 +55,7 @@ export declare const AuthError: {
         readonly JWKS_FETCH_FAILED: "AUTH-070";
         readonly JWKS_KEY_NOT_FOUND: "AUTH-071";
     };
-    create: (code: "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_ERROR" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CONFIGURATION_ERROR" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "RATE_LIMITED" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
+    create: (code: "SESSION_NOT_FOUND" | "RATE_LIMITED" | "CONFIGURATION_ERROR" | "PROVIDER_ERROR" | "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
         retryable?: boolean;
         details?: Record<string, unknown>;
         cause?: Error;

package/dist/lib/auth/index.d.ts

@@ -27,3 +27,14 @@ export { createSessionStorage, MemorySessionStorage, RedisSessionStorage, Sessio
 export { AuthContextHolder, createAuthenticatedContext, getAuthContext, getCurrentSession, getCurrentUser, globalAuthContext, hasAllPermissions, hasAnyRole, hasPermission, hasRole, isAuthenticated, requireAuth, requirePermission, requireRole, requireUser, runWithAuthContext, } from "./authContext.js";
 export { RequestContext, NEUROLINK_RESOURCE_ID_KEY, NEUROLINK_THREAD_ID_KEY, } from "./RequestContext.js";
 export { createAuthValidatorFromProvider } from "./serverBridge.js";
+export { Auth0Provider } from "./providers/auth0.js";
+export { BetterAuthProvider } from "./providers/betterAuth.js";
+export { ClerkProvider } from "./providers/clerk.js";
+export { CognitoProvider } from "./providers/CognitoProvider.js";
+export { CustomAuthProvider } from "./providers/custom.js";
+export { FirebaseAuthProvider } from "./providers/firebase.js";
+export { JWTProvider } from "./providers/jwt.js";
+export { KeycloakProvider } from "./providers/KeycloakProvider.js";
+export { OAuth2Provider } from "./providers/oauth2.js";
+export { SupabaseAuthProvider } from "./providers/supabase.js";
+export { WorkOSProvider } from "./providers/workos.js";

package/dist/lib/auth/index.js

@@ -65,4 +65,18 @@ export { RequestContext, NEUROLINK_RESOURCE_ID_KEY, NEUROLINK_THREAD_ID_KEY, } f
 // Auth Types
 // Server Bridge
 export { createAuthValidatorFromProvider } from "./serverBridge.js";
+// =============================================================================
+// AUTH PROVIDER CLASSES — public re-exports (match the module docstring above)
+// =============================================================================
+export { Auth0Provider } from "./providers/auth0.js";
+export { BetterAuthProvider } from "./providers/betterAuth.js";
+export { ClerkProvider } from "./providers/clerk.js";
+export { CognitoProvider } from "./providers/CognitoProvider.js";
+export { CustomAuthProvider } from "./providers/custom.js";
+export { FirebaseAuthProvider } from "./providers/firebase.js";
+export { JWTProvider } from "./providers/jwt.js";
+export { KeycloakProvider } from "./providers/KeycloakProvider.js";
+export { OAuth2Provider } from "./providers/oauth2.js";
+export { SupabaseAuthProvider } from "./providers/supabase.js";
+export { WorkOSProvider } from "./providers/workos.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/auth/middleware/AuthMiddleware.d.ts

@@ -7,7 +7,7 @@
  * - RBAC enforcement
  * - Public route handling
  */
-import type { AuthenticatedContext, AuthMiddlewareConfig, AuthRequestContext, AuthUser, RBACMiddlewareConfig, TokenExtractionConfig } from "../../types/index.js";
+import type { AuthMiddlewareConfig, AuthMiddlewareHandler, AuthRequestContext, AuthenticatedContext, ExpressMiddleware, IncomingRequest, RBACMiddlewareConfig, TokenExtractionConfig } from "../../types/index.js";
 /**
  * Auth middleware error codes
  */
@@ -31,66 +31,12 @@ export declare const AuthMiddlewareError: {
         readonly PROVIDER_ERROR: "AUTH_MIDDLEWARE-005";
         readonly CONFIGURATION_ERROR: "AUTH_MIDDLEWARE-006";
     };
-    create: (code: "INVALID_TOKEN" | "MISSING_TOKEN" | "PROVIDER_ERROR" | "CONFIGURATION_ERROR" | "UNAUTHORIZED" | "FORBIDDEN", message: string, options?: {
+    create: (code: "UNAUTHORIZED" | "FORBIDDEN" | "CONFIGURATION_ERROR" | "PROVIDER_ERROR" | "INVALID_TOKEN" | "MISSING_TOKEN", message: string, options?: {
         retryable?: boolean;
         details?: Record<string, unknown>;
         cause?: Error;
     } | undefined) => import("../../core/infrastructure/baseError.js").NeuroLinkFeatureError;
 };
-/**
- * Minimal request object accepted by {@link createRequestContext}.
- *
- * Avoids `any` for Express/Koa/Hono request objects while remaining
- * compatible with any framework that exposes these standard fields.
- */
-type IncomingRequest = {
-    method?: string;
-    url?: string;
-    path?: string;
-    headers?: Record<string, string | string[] | undefined>;
-    cookies?: Record<string, string>;
-    query?: Record<string, string | string[] | undefined>;
-    body?: unknown;
-    ip?: string;
-    /** Populated by auth middleware after successful authentication */
-    user?: AuthUser;
-    /** Populated by auth middleware after successful authentication */
-    authContext?: AuthenticatedContext;
-};
-/**
- * Minimal response object for Express-style middleware.
- */
-type OutgoingResponse = {
-    status(code: number): OutgoingResponse;
-    json(body: unknown): void;
-};
-/**
- * Middleware handler function type
- */
-type MiddlewareHandler<TContext = AuthRequestContext> = (context: TContext) => Promise<MiddlewareResult>;
-/**
- * Middleware result
- */
-type MiddlewareResult = {
-    /** Whether to proceed to next handler */
-    proceed: boolean;
-    /** Updated context (if authenticated) */
-    context?: AuthenticatedContext;
-    /** Error response if not proceeding */
-    error?: {
-        statusCode: number;
-        message: string;
-        code?: string;
-    };
-};
-/**
- * Next function for middleware chaining
- */
-type NextFunction = () => Promise<void>;
-/**
- * Express-style middleware function
- */
-type ExpressMiddleware = (req: IncomingRequest, res: OutgoingResponse, next: NextFunction) => Promise<void>;
 /**
  * Extract token from request context based on configuration
  */
@@ -123,7 +69,7 @@ export declare function extractToken(context: AuthRequestContext, config?: Token
  * }
  * ```
  */
-export declare function createAuthMiddleware(config: AuthMiddlewareConfig): Promise<MiddlewareHandler<AuthRequestContext>>;
+export declare function createAuthMiddleware(config: AuthMiddlewareConfig): Promise<AuthMiddlewareHandler<AuthRequestContext>>;
 /**
  * Create RBAC (Role-Based Access Control) middleware
  *
@@ -146,7 +92,7 @@ export declare function createAuthMiddleware(config: AuthMiddlewareConfig): Prom
  * }
  * ```
  */
-export declare function createRBACMiddleware(config: RBACMiddlewareConfig): MiddlewareHandler<AuthenticatedContext>;
+export declare function createRBACMiddleware(config: RBACMiddlewareConfig): AuthMiddlewareHandler<AuthenticatedContext>;
 /**
  * Create combined auth + RBAC middleware
  *
@@ -170,7 +116,7 @@ export declare function createRBACMiddleware(config: RBACMiddlewareConfig): Midd
 export declare function createProtectedMiddleware(config: {
     auth: AuthMiddlewareConfig;
     rbac?: RBACMiddlewareConfig;
-}): Promise<MiddlewareHandler<AuthRequestContext>>;
+}): Promise<AuthMiddlewareHandler<AuthRequestContext>>;
 /**
  * Create request context from standard request object
  */
@@ -179,4 +125,3 @@ export declare function createRequestContext(req: IncomingRequest): AuthRequestC
  * Create Express-compatible middleware
  */
 export declare function createExpressAuthMiddleware(config: AuthMiddlewareConfig): Promise<ExpressMiddleware>;
-export {};

package/dist/lib/auth/middleware/AuthMiddleware.js

@@ -43,6 +43,9 @@ function createAuthErrorInfo(message, code) {
     return err;
 }
 // =============================================================================
+// TYPES
+// =============================================================================
+// =============================================================================
 // TOKEN EXTRACTION
 // =============================================================================
 /**

package/dist/lib/auth/middleware/rateLimitByUser.d.ts

@@ -1,84 +1,4 @@
-import type { AuthenticatedContext, AuthRequestContext, AuthUser } from "../../types/index.js";
-/**
- * Token bucket state for a single user
- */
-type TokenBucket = {
-    /** Current number of tokens available */
-    tokens: number;
-    /** Last time tokens were added */
-    lastRefill: number;
-    /** User identifier */
-    userId: string;
-};
-/**
- * Rate limit configuration per user or role
- */
-type RateLimitConfig = {
-    /** Maximum requests allowed in the window */
-    maxRequests: number;
-    /** Time window in milliseconds */
-    windowMs: number;
-    /** Optional: Different limits per role (role -> maxRequests) */
-    roleLimits?: Record<string, number>;
-    /** Optional: Different limits per user ID (userId -> maxRequests) */
-    userLimits?: Record<string, number>;
-    /** Skip rate limiting for these roles */
-    skipRoles?: string[];
-    /** Error message when rate limited */
-    message?: string;
-};
-/**
- * Rate limit result
- */
-type RateLimitResult = {
-    /** Whether the request is allowed */
-    allowed: boolean;
-    /** Remaining requests in the current window */
-    remaining: number;
-    /** Time until the bucket resets (ms) */
-    resetIn: number;
-    /** Total limit for this user */
-    limit: number;
-    /** Error message if rate limited */
-    error?: string;
-};
-/**
- * Result of an atomic consume operation
- */
-type AtomicConsumeResult = {
-    /** Updated bucket after the operation */
-    bucket: TokenBucket;
-    /** Whether a token was successfully consumed */
-    consumed: boolean;
-};
-/**
- * Interface for rate limit storage backends
- */
-type RateLimitStorage = {
-    /** Get the current bucket for a user */
-    getBucket(userId: string): Promise<TokenBucket | null>;
-    /** Set the bucket for a user */
-    setBucket(userId: string, bucket: TokenBucket): Promise<void>;
-    /** Delete a bucket (for cleanup) */
-    deleteBucket(userId: string): Promise<void>;
-    /** Check storage health */
-    healthCheck(): Promise<boolean>;
-    /** Cleanup resources */
-    cleanup(): Promise<void>;
-    /**
-     * Atomically refill and consume a token from the bucket.
-     *
-     * Implementations SHOULD perform the refill-and-consume in a single
-     * atomic step (e.g. Lua script for Redis) to prevent race conditions
-     * where parallel requests read the same token count and both succeed.
-     *
-     * The default in-memory implementation is inherently single-threaded,
-     * so atomicity comes for free.
-     *
-     * @returns null when no bucket exists yet (caller should create one)
-     */
-    atomicConsume?(userId: string, limit: number, windowMs: number, nowMs: number): Promise<AtomicConsumeResult | null>;
-};
+import type { AtomicConsumeResult, AuthRateLimitConfig, AuthRequestContext, AuthUser, AuthenticatedContext, RateLimitMiddlewareResult, RateLimitResult, RateLimitStorage, TokenBucket } from "../../types/index.js";
 /**
  * In-memory storage for rate limiting (single instance deployments)
  */
@@ -136,7 +56,7 @@ export declare class RedisRateLimitStorage implements RateLimitStorage {
 export declare class UserRateLimiter {
     private storage;
     private config;
-    constructor(config: RateLimitConfig, storage?: RateLimitStorage);
+    constructor(config: AuthRateLimitConfig, storage?: RateLimitStorage);
     /**
      * Get the rate limit for a specific user based on their roles
      */
@@ -175,14 +95,6 @@ export declare class UserRateLimiter {
 /**
  * Middleware result type
  */
-type RateLimitMiddlewareResult = {
-    /** Whether to proceed with the request */
-    proceed: boolean;
-    /** Rate limit result */
-    rateLimitResult: RateLimitResult;
-    /** Error response if rate limited */
-    response?: Response;
-};
 /**
  * Create rate limiting middleware for authenticated requests
  *
@@ -212,7 +124,7 @@ type RateLimitMiddlewareResult = {
  * });
  * ```
  */
-export declare function createRateLimitByUserMiddleware(config: RateLimitConfig, storage?: RateLimitStorage): (context: AuthenticatedContext) => Promise<RateLimitMiddlewareResult>;
+export declare function createRateLimitByUserMiddleware(config: AuthRateLimitConfig, storage?: RateLimitStorage): (context: AuthenticatedContext) => Promise<RateLimitMiddlewareResult>;
 /**
  * Create a combined auth and rate limit middleware
  *
@@ -242,7 +154,7 @@ export declare function createAuthenticatedRateLimitMiddleware(authMiddleware: (
     proceed: boolean;
     context?: AuthenticatedContext;
     response?: Response;
-}>, rateLimitConfig: RateLimitConfig, storage?: RateLimitStorage): (context: AuthRequestContext) => Promise<{
+}>, rateLimitConfig: AuthRateLimitConfig, storage?: RateLimitStorage): (context: AuthRequestContext) => Promise<{
     proceed: boolean;
     context?: AuthenticatedContext;
     rateLimitResult?: RateLimitResult;
@@ -279,4 +191,3 @@ export declare function createRateLimitStorage(config: {
     };
     cleanupIntervalMs?: number;
 }): RateLimitStorage;
-export {};

package/dist/lib/auth/middleware/rateLimitByUser.js

@@ -217,6 +217,7 @@ export class RedisRateLimitStorage {
         }
     }
 }
+// Type for Redis client (simplified interface)
 /**
  * Token bucket rate limiter implementation
  *
@@ -406,6 +407,9 @@ export class UserRateLimiter {
         await this.storage.cleanup();
     }
 }
+/**
+ * Middleware result type
+ */
 /**
  * Create rate limiting middleware for authenticated requests
  *

package/dist/lib/auth/providers/BaseAuthProvider.d.ts

@@ -44,7 +44,7 @@ export declare const AuthProviderError: {
         readonly JWKS_FETCH_FAILED: "AUTH-070";
         readonly JWKS_KEY_NOT_FOUND: "AUTH-071";
     };
-    create: (code: "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_ERROR" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CONFIGURATION_ERROR" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "RATE_LIMITED" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
+    create: (code: "SESSION_NOT_FOUND" | "RATE_LIMITED" | "CONFIGURATION_ERROR" | "PROVIDER_ERROR" | "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
         retryable?: boolean;
         details?: Record<string, unknown>;
         cause?: Error;

package/dist/lib/auth/providers/CognitoProvider.js

@@ -7,6 +7,9 @@ import { importJWK, jwtVerify } from "jose";
 import { logger } from "../../utils/logger.js";
 import { AuthError } from "../errors.js";
 import { BaseAuthProvider } from "./BaseAuthProvider.js";
+// =============================================================================
+// JWKS CACHE
+// =============================================================================
 const jwksCache = new Map();
 // =============================================================================
 // COGNITO PROVIDER

package/dist/lib/auth/providers/KeycloakProvider.js

@@ -7,6 +7,9 @@ import { importJWK, jwtVerify } from "jose";
 import { logger } from "../../utils/logger.js";
 import { AuthError } from "../errors.js";
 import { BaseAuthProvider } from "./BaseAuthProvider.js";
+// =============================================================================
+// JWKS CACHE
+// =============================================================================
 const jwksCache = new Map();
 // =============================================================================
 // KEYCLOAK PROVIDER

package/dist/lib/auth/providers/auth0.d.ts

@@ -1,5 +1,5 @@
 import { BaseAuthProvider } from "./BaseAuthProvider.js";
-import type { AuthProviderConfig, Auth0Config, AuthUser, TokenValidationResult, AuthRequestContext, AuthHealthCheck, AuthProviderType } from "../../types/index.js";
+import type { Auth0Config, AuthHealthCheck, AuthProviderConfig, AuthProviderType, AuthRequestContext, AuthUser, TokenValidationResult } from "../../types/index.js";
 /**
  * Auth0 Authentication Provider
  *

package/dist/lib/auth/sessionManager.d.ts

@@ -67,12 +67,14 @@ export declare class SessionManager {
         userAgent?: string;
         deviceId?: string;
     }): Promise<AuthSession>;
+    private _createSession;
     /**
      * Get a session by ID
      *
      * Optionally auto-refreshes if close to expiration.
      */
     getSession(sessionId: string, autoRefresh?: boolean | undefined): Promise<AuthSession | null>;
+    private _getSession;
     /**
      * Check if session should be refreshed
      */

package/dist/lib/auth/sessionManager.js

@@ -1,6 +1,8 @@
 // src/lib/auth/sessionManager.ts
 import { withTimeout } from "../utils/async/withTimeout.js";
 import { logger } from "../utils/logger.js";
+import { withSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 /** Mask an identifier for safe logging: show first 4 chars + "***" */
 function maskId(id) {
     if (id.length <= 4) {
@@ -333,6 +335,16 @@ export class SessionManager {
      * Create a new session
      */
     async createSession(user, metadata) {
+        return withSpan({
+            name: "neurolink.auth.session.create",
+            tracer: tracers.auth,
+            attributes: {
+                "auth.user_id": maskId(user.id),
+                "auth.storage": this.config.storage ?? "memory",
+            },
+        }, async () => this._createSession(user, metadata));
+    }
+    async _createSession(user, metadata) {
         const sessionId = crypto.randomUUID();
         const now = new Date();
         const duration = this.config.duration || 3600;
@@ -356,6 +368,20 @@ export class SessionManager {
      * Optionally auto-refreshes if close to expiration.
      */
     async getSession(sessionId, autoRefresh = this.config.autoRefresh) {
+        return withSpan({
+            name: "neurolink.auth.session.get",
+            tracer: tracers.auth,
+            attributes: {
+                "auth.session_id": maskId(sessionId),
+                "auth.auto_refresh": autoRefresh ?? false,
+            },
+        }, async (span) => {
+            const result = await this._getSession(sessionId, autoRefresh);
+            span.setAttribute("auth.found", result !== null);
+            return result;
+        });
+    }
+    async _getSession(sessionId, autoRefresh = this.config.autoRefresh) {
         const session = await this.storage.get(sessionId);
         if (!session) {
             return null;
@@ -381,15 +407,23 @@ export class SessionManager {
      * Refresh a session
      */
     async refreshSession(sessionId) {
-        const session = await this.storage.get(sessionId);
-        if (!session) {
-            return null;
-        }
-        const duration = this.config.duration || 3600;
-        session.expiresAt = new Date(Date.now() + duration * 1000);
-        await this.storage.set(session);
-        logger.debug(`Session refreshed: ${maskId(sessionId)}`);
-        return session;
+        return withSpan({
+            name: "neurolink.auth.session.refresh",
+            tracer: tracers.auth,
+            attributes: { "auth.session_id": maskId(sessionId) },
+        }, async (span) => {
+            const session = await this.storage.get(sessionId);
+            if (!session) {
+                span.setAttribute("auth.found", false);
+                return null;
+            }
+            const duration = this.config.duration || 3600;
+            session.expiresAt = new Date(Date.now() + duration * 1000);
+            await this.storage.set(session);
+            span.setAttribute("auth.found", true);
+            logger.debug(`Session refreshed: ${maskId(sessionId)}`);
+            return session;
+        });
     }
     /**
      * Destroy a session
@@ -415,8 +449,16 @@ export class SessionManager {
      * Validate a session is still active
      */
     async validateSession(sessionId) {
-        const session = await this.storage.get(sessionId);
-        return session !== null && session.isValid;
+        return withSpan({
+            name: "neurolink.auth.session.validate",
+            tracer: tracers.auth,
+            attributes: { "auth.session_id": maskId(sessionId) },
+        }, async (span) => {
+            const session = await this.storage.get(sessionId);
+            const valid = session !== null && session.isValid;
+            span.setAttribute("auth.valid", valid);
+            return valid;
+        });
     }
     /**
      * Update session metadata

package/dist/lib/auth/tokenStore.d.ts

@@ -107,6 +107,7 @@ export declare class TokenStore {
      * @throws TokenStoreError if deletion fails
      */
     clearTokens(provider: string): Promise<void>;
+    private _clearTokensImpl;
     /**
      * Checks if the given tokens are expired
      *
@@ -126,6 +127,7 @@ export declare class TokenStore {
      * @throws TokenStoreError if refresh fails
      */
     getValidToken(provider: string): Promise<string | null>;
+    private _getValidTokenImpl;
     /**
      * Sets the token refresher function for a provider
      *

package/dist/lib/auth/tokenStore.js

@@ -19,6 +19,8 @@ import { createHash } from "crypto";
 import { logger } from "../utils/logger.js";
 import { TokenStoreError } from "../types/index.js";
 import { AsyncMutex } from "../utils/asyncMutex.js";
+import { withSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 const { readFile, writeFile, mkdir, unlink, access, chmod, rename } = fs;
 // =============================================================================
 // TOKEN STORE CLASS
@@ -106,9 +108,17 @@ export class TokenStore {
      * @throws TokenStoreError if storage fails
      */
     async saveTokens(provider, tokens) {
-        return this._mutex.runExclusive(async () => {
+        return withSpan({
+            name: "neurolink.auth.token.save",
+            tracer: tracers.auth,
+            attributes: {
+                "auth.provider": provider,
+                "auth.has_refresh_token": Boolean(tokens.refreshToken),
+                "auth.token_type": tokens.tokenType,
+            },
+        }, async () => this._mutex.runExclusive(async () => {
             await this._saveTokensInternal(provider, tokens);
-        });
+        }));
     }
     /**
      * Internal save without mutex — callers must already hold the mutex.
@@ -178,8 +188,19 @@ export class TokenStore {
      * @throws TokenStoreError if reading fails (other than file not found)
      */
     async loadTokens(provider) {
-        return this._mutex.runExclusive(async () => {
-            return this._loadTokensInternal(provider);
+        return withSpan({
+            name: "neurolink.auth.token.load",
+            tracer: tracers.auth,
+            attributes: { "auth.provider": provider },
+        }, async (span) => {
+            const result = await this._mutex.runExclusive(async () => {
+                return this._loadTokensInternal(provider);
+            });
+            span.setAttribute("auth.found", result !== null);
+            if (result) {
+                span.setAttribute("auth.expired", this.isTokenExpired(result, 0));
+            }
+            return result;
         });
     }
     /**
@@ -217,6 +238,13 @@ export class TokenStore {
      * @throws TokenStoreError if deletion fails
      */
     async clearTokens(provider) {
+        return withSpan({
+            name: "neurolink.auth.token.clear",
+            tracer: tracers.auth,
+            attributes: { "auth.provider": provider },
+        }, async () => this._clearTokensImpl(provider));
+    }
+    async _clearTokensImpl(provider) {
         return this._mutex.runExclusive(async () => {
             // Clear in-memory refresh state so re-adding an account starts fresh
             this.inFlightRefreshes.delete(provider);
@@ -274,6 +302,13 @@ export class TokenStore {
      * @throws TokenStoreError if refresh fails
      */
     async getValidToken(provider) {
+        return withSpan({
+            name: "neurolink.auth.token.get_valid",
+            tracer: tracers.auth,
+            attributes: { "auth.provider": provider },
+        }, async (span) => this._getValidTokenImpl(provider, span));
+    }
+    async _getValidTokenImpl(provider, span) {
         // Phase 1: Read token under mutex (fast)
         const snapshot = await this._mutex.runExclusive(async () => {
             const tokens = await this._loadTokensInternal(provider);
@@ -283,13 +318,18 @@ export class TokenStore {
             return { ...tokens };
         });
         if (!snapshot) {
+            span.setAttribute("auth.found", false);
             logger.debug("No tokens found for provider", { provider });
             return null;
         }
+        span.setAttribute("auth.found", true);
         // Token is still valid — return immediately
         if (!this.isTokenExpired(snapshot)) {
+            span.setAttribute("auth.refreshed", false);
+            span.setAttribute("auth.expired", false);
             return snapshot.accessToken;
         }
+        span.setAttribute("auth.expired", true);
         logger.debug("Token expired or expiring soon", {
             provider,
             expiresAt: new Date(snapshot.expiresAt).toISOString(),
@@ -368,6 +408,7 @@ export class TokenStore {
         this.inFlightRefreshes.set(provider, refreshPromise);
         try {
             const newTokens = await refreshPromise;
+            span.setAttribute("auth.refreshed", true);
             return newTokens.accessToken;
         }
         finally {

package/dist/lib/autoresearch/tools.d.ts

@@ -7,21 +7,7 @@
  *
  * @module autoresearch/tools
  */
-import type { ExperimentRecord, ResearchConfig } from "../types/index.js";
-import type { RepoPolicy } from "./repoPolicy.js";
-import type { ResultRecorder } from "./resultRecorder.js";
-import type { ExperimentRunner } from "./runner.js";
-import type { ResearchStateStore } from "./stateStore.js";
-/**
- * Dependencies required to create research tools.
- */
-type ResearchToolsDeps = {
-    config: ResearchConfig;
-    stateStore: ResearchStateStore;
-    repoPolicy: RepoPolicy;
-    runner: ExperimentRunner;
-    recorder: ResultRecorder;
-};
+import type { ExperimentRecord, ResearchToolsDeps } from "../types/index.js";
 /**
  * Create research management tools bound to a research session.
  *
@@ -251,4 +237,3 @@ export declare function createResearchTools(deps: ResearchToolsDeps): {
         error?: undefined;
     }>;
 };
-export {};

package/dist/lib/client/aiSdkAdapter.d.ts

@@ -7,7 +7,7 @@
  *
  * @module @neurolink/ai-sdk
  */
-import type { ClientLanguageModel, ClientLanguageModelCallOptions, ClientLanguageModelResponse, ClientLanguageModelStreamResponse, NeuroLinkProviderOptions, ClientModelOptions } from "../types/index.js";
+import type { ClientLanguageModel, ClientLanguageModelCallOptions, ClientLanguageModelResponse, ClientLanguageModelStreamResponse, ClientModelOptions, NeuroLinkProviderOptions } from "../types/index.js";
 import { NeuroLinkClient } from "./httpClient.js";
 /**
  * NeuroLink Language Model implementation compatible with Vercel AI SDK

package/dist/lib/client/aiSdkAdapter.js

@@ -107,6 +107,7 @@ export class NeuroLinkLanguageModel {
         }
         // Extract system message if present
         const systemPrompt = system ?? messages?.find((m) => m.role === "system")?.content;
+        // ---- Async queue (push/pull pattern) ----
         const buffer = [];
         let finished = false;
         let notifyConsumer = null;

package/dist/lib/client/httpClient.d.ts

@@ -99,6 +99,7 @@ export declare class NeuroLinkClient {
      * Execute HTTP request with middleware and retry logic
      */
     private request;
+    private _doRequest;
     /**
      * Generate text using AI models
      *