@oxyhq/core 1.2.2 → 1.2.4

package/dist/esm/mixins/OxyServices.utility.js

@@ -26,122 +26,215 @@ export function OxyServicesUtilityMixin(Base) {
             }
         }
         /**
-         * Simple Express.js authentication middleware
+         * Express.js authentication middleware
          *
-         * Built-in authentication middleware that validates JWT tokens and adds user data to requests.
+         * Validates JWT tokens against the Oxy API and attaches user data to requests.
+         * Uses server-side session validation for security (not just JWT decode).
          *
          * @example
          * ```typescript
-         * // Basic usage - just add it to your routes
-         * app.use('/api/protected', oxyServices.auth());
+         * import { OxyServices } from '@oxyhq/core';
          *
-         * // With debug logging
-         * app.use('/api/protected', oxyServices.auth({ debug: true }));
+         * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
          *
-         * // With custom error handling
-         * app.use('/api/protected', oxyServices.auth({
-         *   onError: (error) => console.error('Auth failed:', error)
-         * }));
+         * // Protect all routes under /api/protected
+         * app.use('/api/protected', oxy.auth());
          *
-         * // Load full user data
-         * app.use('/api/protected', oxyServices.auth({ loadUser: true }));
+         * // Access user in route handler
+         * app.get('/api/protected/me', (req, res) => {
+         *   res.json({ userId: req.userId, user: req.user });
+         * });
+         *
+         * // Load full user profile from API
+         * app.use('/api/admin', oxy.auth({ loadUser: true }));
+         *
+         * // Optional auth - attach user if present, don't block if absent
+         * app.use('/api/public', oxy.auth({ optional: true }));
          * ```
          *
          * @param options Optional configuration
-         * @param options.debug Enable debug logging (default: false)
-         * @param options.onError Custom error handler
-         * @param options.loadUser Load full user data (default: false for performance)
-         * @param options.session Use session-based validation (default: false)
          * @returns Express middleware function
          */
         auth(options = {}) {
-            const { debug = false, onError, loadUser = false, session = false } = options;
-            // Return a synchronous middleware function
-            return (req, res, next) => {
+            const { debug = false, onError, loadUser = false, optional = false } = options;
+            // Cast to any for cross-mixin method access (Auth mixin methods available at runtime)
+            const oxyInstance = this;
+            // Return an async middleware function
+            return async (req, res, next) => {
                 try {
-                    // Extract token from Authorization header
+                    // Extract token from Authorization header or query params
                     const authHeader = req.headers['authorization'];
-                    const token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
+                    let token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
+                    // Fallback to query params (useful for WebSocket upgrades)
+                    if (!token) {
+                        const q = req.query || {};
+                        if (typeof q.token === 'string' && q.token)
+                            token = q.token;
+                        else if (typeof q.access_token === 'string' && q.access_token)
+                            token = q.access_token;
+                    }
                     if (debug) {
-                        console.log(`🔐 Auth: Processing ${req.method} ${req.path}`);
-                        console.log(`🔐 Auth: Token present: ${!!token}`);
+                        console.log(`[oxy.auth] ${req.method} ${req.path} | token: ${!!token}`);
                     }
                     if (!token) {
+                        if (optional) {
+                            req.userId = null;
+                            req.user = null;
+                            return next();
+                        }
                         const error = {
                             message: 'Access token required',
                             code: 'MISSING_TOKEN',
                             status: 401
                         };
-                        if (debug)
-                            console.log(`❌ Auth: Missing token`);
                         if (onError)
                             return onError(error);
                         return res.status(401).json(error);
                     }
-                    // Decode and validate token
+                    // Decode token to extract claims
                     let decoded;
                     try {
                         decoded = jwtDecode(token);
-                        if (debug) {
-                            console.log(`🔐 Auth: Token decoded, User ID: ${decoded.userId || decoded.id}`);
-                        }
                     }
                     catch (decodeError) {
+                        if (optional) {
+                            req.userId = null;
+                            req.user = null;
+                            return next();
+                        }
                         const error = {
                             message: 'Invalid token format',
                             code: 'INVALID_TOKEN_FORMAT',
-                            status: 403
+                            status: 401
                         };
-                        if (debug)
-                            console.log(`❌ Auth: Token decode failed`);
                         if (onError)
                             return onError(error);
-                        return res.status(403).json(error);
+                        return res.status(401).json(error);
                     }
                     const userId = decoded.userId || decoded.id;
                     if (!userId) {
+                        if (optional) {
+                            req.userId = null;
+                            req.user = null;
+                            return next();
+                        }
                         const error = {
                             message: 'Token missing user ID',
                             code: 'INVALID_TOKEN_PAYLOAD',
-                            status: 403
+                            status: 401
                         };
-                        if (debug)
-                            console.log(`❌ Auth: Token missing user ID`);
                         if (onError)
                             return onError(error);
-                        return res.status(403).json(error);
+                        return res.status(401).json(error);
                     }
-                    // Check token expiration
+                    // Check token expiration locally first (fast path)
                     if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                        if (optional) {
+                            req.userId = null;
+                            req.user = null;
+                            return next();
+                        }
                         const error = {
                             message: 'Token expired',
                             code: 'TOKEN_EXPIRED',
-                            status: 403
+                            status: 401
                         };
-                        if (debug)
-                            console.log(`❌ Auth: Token expired`);
                         if (onError)
                             return onError(error);
-                        return res.status(403).json(error);
+                        return res.status(401).json(error);
+                    }
+                    // Validate token against the Oxy API for session-based verification
+                    // This ensures the session hasn't been revoked server-side
+                    if (decoded.sessionId) {
+                        try {
+                            const validationResult = await oxyInstance.validateSession(decoded.sessionId, {
+                                useHeaderValidation: true,
+                            });
+                            if (!validationResult || !validationResult.valid) {
+                                if (optional) {
+                                    req.userId = null;
+                                    req.user = null;
+                                    return next();
+                                }
+                                const error = {
+                                    message: 'Session invalid or expired',
+                                    code: 'INVALID_SESSION',
+                                    status: 401
+                                };
+                                if (onError)
+                                    return onError(error);
+                                return res.status(401).json(error);
+                            }
+                            // Use validated user data from session validation (already has full user)
+                            req.userId = userId;
+                            req.accessToken = token;
+                            req.sessionId = decoded.sessionId;
+                            if (loadUser && validationResult.user) {
+                                // Session validation already returns full user data
+                                req.user = validationResult.user;
+                            }
+                            else {
+                                req.user = { id: userId };
+                            }
+                            if (debug) {
+                                console.log(`[oxy.auth] OK user=${userId} session=${decoded.sessionId}`);
+                            }
+                            return next();
+                        }
+                        catch (validationError) {
+                            if (debug) {
+                                console.log(`[oxy.auth] Session validation failed:`, validationError);
+                            }
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = {
+                                message: 'Session validation failed',
+                                code: 'SESSION_VALIDATION_ERROR',
+                                status: 401
+                            };
+                            if (onError)
+                                return onError(error);
+                            return res.status(401).json(error);
+                        }
                     }
-                    // For now, skip session validation to keep it simple
-                    // Session validation can be added later if needed
-                    // Set request properties immediately
+                    // Non-session token: use local validation only (userId from JWT)
                     req.userId = userId;
                     req.accessToken = token;
                     req.user = { id: userId };
-                    // Automatically authenticate the OxyServices instance so all subsequent API calls are authenticated
-                    this.setTokens(token);
+                    // If loadUser requested with non-session token, fetch from API
+                    if (loadUser) {
+                        try {
+                            // Temporarily set token to make the API call
+                            const prevToken = oxyInstance.getAccessToken();
+                            oxyInstance.setTokens(token);
+                            const fullUser = await oxyInstance.getCurrentUser();
+                            // Restore previous token
+                            if (prevToken) {
+                                oxyInstance.setTokens(prevToken);
+                            }
+                            else {
+                                oxyInstance.clearTokens();
+                            }
+                            if (fullUser) {
+                                req.user = fullUser;
+                            }
+                        }
+                        catch {
+                            // Failed to load user, continue with basic user object
+                        }
+                    }
                     if (debug) {
-                        console.log(`✅ Auth: Authentication successful for user ${userId}`);
+                        console.log(`[oxy.auth] OK user=${userId} (no session)`);
                     }
                     next();
                 }
                 catch (error) {
-                    const apiError = this.handleError(error);
+                    const apiError = oxyInstance.handleError(error);
                     if (debug) {
-                        // Debug logging - using console.log is acceptable here for development
-                        console.log(`❌ Auth: Unexpected error:`, apiError);
+                        console.log(`[oxy.auth] Error:`, apiError);
                     }
                     if (onError)
                         return onError(apiError);
@@ -149,5 +242,86 @@ export function OxyServicesUtilityMixin(Base) {
                 }
             };
         }
+        /**
+         * Socket.IO authentication middleware factory
+         *
+         * Returns a middleware function for Socket.IO that validates JWT tokens
+         * from the handshake auth object and attaches user data to the socket.
+         *
+         * @example
+         * ```typescript
+         * import { OxyServices } from '@oxyhq/core';
+         * import { Server } from 'socket.io';
+         *
+         * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+         * const io = new Server(server);
+         *
+         * // Authenticate all socket connections
+         * io.use(oxy.authSocket());
+         *
+         * io.on('connection', (socket) => {
+         *   console.log('Authenticated user:', socket.data.userId);
+         * });
+         * ```
+         */
+        authSocket(options = {}) {
+            const { debug = false } = options;
+            // Cast to any for cross-mixin method access (Auth mixin methods available at runtime)
+            const oxyInstance = this;
+            return async (socket, next) => {
+                try {
+                    const token = socket.handshake?.auth?.token;
+                    if (!token) {
+                        return next(new Error('Authentication required'));
+                    }
+                    let decoded;
+                    try {
+                        decoded = jwtDecode(token);
+                    }
+                    catch {
+                        return next(new Error('Invalid token'));
+                    }
+                    const userId = decoded.userId || decoded.id;
+                    if (!userId) {
+                        return next(new Error('Invalid token payload'));
+                    }
+                    // Check expiration
+                    if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                        return next(new Error('Token expired'));
+                    }
+                    // Validate session if available
+                    if (decoded.sessionId) {
+                        try {
+                            const result = await oxyInstance.validateSession(decoded.sessionId, {
+                                useHeaderValidation: true,
+                            });
+                            if (!result || !result.valid) {
+                                return next(new Error('Session invalid'));
+                            }
+                        }
+                        catch {
+                            return next(new Error('Session validation failed'));
+                        }
+                    }
+                    // Attach user data to socket
+                    socket.data = socket.data || {};
+                    socket.data.userId = userId;
+                    socket.data.sessionId = decoded.sessionId || null;
+                    socket.data.token = token;
+                    // Also set on socket.user for backward compatibility
+                    socket.user = { id: userId, userId, sessionId: decoded.sessionId };
+                    if (debug) {
+                        console.log(`[oxy.authSocket] OK user=${userId}`);
+                    }
+                    next();
+                }
+                catch (err) {
+                    if (debug) {
+                        console.log(`[oxy.authSocket] Error:`, err);
+                    }
+                    next(new Error('Authentication error'));
+                }
+            };
+        }
     };
 }

package/dist/types/HttpService.d.ts

@@ -28,6 +28,8 @@ interface RequestConfig extends RequestOptions {
     url: string;
     data?: unknown;
     params?: Record<string, unknown>;
+    /** @internal Used to prevent infinite auth retry loops */
+    _isAuthRetry?: boolean;
 }
 /**
  * Unified HTTP Service
@@ -44,6 +46,7 @@ export declare class HttpService {
     private logger;
     private config;
     private tokenRefreshPromise;
+    private _onTokenRefreshed;
     private requestMetrics;
     constructor(config: OxyConfig);
     /**
@@ -140,6 +143,7 @@ export declare class HttpService {
         data: T;
     }>;
     setTokens(accessToken: string, refreshToken?: string): void;
+    set onTokenRefreshed(callback: ((accessToken: string) => void) | null);
     clearTokens(): void;
     getAccessToken(): string | null;
     hasAccessToken(): boolean;

package/dist/types/OxyServices.d.ts

@@ -77,6 +77,15 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     signUpWithPopup(options?: PopupAuthOptions): Promise<SessionLoginResponse>;
     signInWithRedirect(options?: RedirectAuthOptions): void;
     signUpWithRedirect(options?: RedirectAuthOptions): void;
+    auth(options?: {
+        debug?: boolean;
+        onError?: (error: any) => any;
+        loadUser?: boolean;
+        optional?: boolean;
+    }): (req: any, res: any, next: any) => Promise<void>;
+    authSocket(options?: {
+        debug?: boolean;
+    }): (socket: any, next: (err?: Error) => void) => Promise<void>;
 }
 export { OxyAuthenticationError, OxyAuthenticationTimeoutError };
 /**

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -1,5 +1,18 @@
 import type { ApiError } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * Options for oxyClient.auth() middleware
+ */
+interface AuthMiddlewareOptions {
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom error handler - receives error object, can return response */
+    onError?: (error: ApiError) => any;
+    /** Load full user profile from API (default: false for performance) */
+    loadUser?: boolean;
+    /** Optional auth - attach user if token present but don't block (default: false) */
+    optional?: boolean;
+}
 export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -12,40 +25,61 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
             image?: string;
         }>;
         /**
-         * Simple Express.js authentication middleware
+         * Express.js authentication middleware
          *
-         * Built-in authentication middleware that validates JWT tokens and adds user data to requests.
+         * Validates JWT tokens against the Oxy API and attaches user data to requests.
+         * Uses server-side session validation for security (not just JWT decode).
          *
          * @example
          * ```typescript
-         * // Basic usage - just add it to your routes
-         * app.use('/api/protected', oxyServices.auth());
+         * import { OxyServices } from '@oxyhq/core';
          *
-         * // With debug logging
-         * app.use('/api/protected', oxyServices.auth({ debug: true }));
+         * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
          *
-         * // With custom error handling
-         * app.use('/api/protected', oxyServices.auth({
-         *   onError: (error) => console.error('Auth failed:', error)
-         * }));
+         * // Protect all routes under /api/protected
+         * app.use('/api/protected', oxy.auth());
          *
-         * // Load full user data
-         * app.use('/api/protected', oxyServices.auth({ loadUser: true }));
+         * // Access user in route handler
+         * app.get('/api/protected/me', (req, res) => {
+         *   res.json({ userId: req.userId, user: req.user });
+         * });
+         *
+         * // Load full user profile from API
+         * app.use('/api/admin', oxy.auth({ loadUser: true }));
+         *
+         * // Optional auth - attach user if present, don't block if absent
+         * app.use('/api/public', oxy.auth({ optional: true }));
          * ```
          *
          * @param options Optional configuration
-         * @param options.debug Enable debug logging (default: false)
-         * @param options.onError Custom error handler
-         * @param options.loadUser Load full user data (default: false for performance)
-         * @param options.session Use session-based validation (default: false)
          * @returns Express middleware function
          */
-        auth(options?: {
+        auth(options?: AuthMiddlewareOptions): (req: any, res: any, next: any) => Promise<any>;
+        /**
+         * Socket.IO authentication middleware factory
+         *
+         * Returns a middleware function for Socket.IO that validates JWT tokens
+         * from the handshake auth object and attaches user data to the socket.
+         *
+         * @example
+         * ```typescript
+         * import { OxyServices } from '@oxyhq/core';
+         * import { Server } from 'socket.io';
+         *
+         * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+         * const io = new Server(server);
+         *
+         * // Authenticate all socket connections
+         * io.use(oxy.authSocket());
+         *
+         * io.on('connection', (socket) => {
+         *   console.log('Authenticated user:', socket.data.userId);
+         * });
+         * ```
+         */
+        authSocket(options?: {
             debug?: boolean;
-            onError?: (error: ApiError) => any;
-            loadUser?: boolean;
-            session?: boolean;
-        }): (req: any, res: any, next: any) => any;
+        }): (socket: any, next: (err?: Error) => void) => Promise<void>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
@@ -93,3 +127,4 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
     };
     __resetTokensForTests(): void;
 } & T;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/AuthManager.ts

@@ -153,6 +153,11 @@ export class AuthManager {
       refreshBuffer: config.refreshBuffer ?? 5 * 60 * 1000, // 5 minutes
     };
     this.storage = this.config.storage;
+
+    // Persist tokens to storage when HttpService refreshes them automatically
+    this.oxyServices.httpService.onTokenRefreshed = (accessToken: string) => {
+      this.storage.setItem(STORAGE_KEYS.ACCESS_TOKEN, accessToken);
+    };
   }
 
   /**
@@ -280,8 +285,19 @@ export class AuthManager {
   }
 
   private async _doRefreshToken(): Promise<boolean> {
-    const refreshToken = await this.storage.getItem(STORAGE_KEYS.REFRESH_TOKEN);
-    if (!refreshToken) {
+    // Get session info to find sessionId for token refresh
+    const sessionJson = await this.storage.getItem(STORAGE_KEYS.SESSION);
+    if (!sessionJson) {
+      return false;
+    }
+
+    let sessionId: string;
+    try {
+      const session = JSON.parse(sessionJson);
+      sessionId = session.sessionId;
+      if (!sessionId) return false;
+} catch (err) {
+      console.error('AuthManager: Failed to parse session from storage.', err);
       return false;
     }
 
@@ -289,13 +305,37 @@ export class AuthManager {
       await retryAsync(
         async () => {
           const httpService = this.oxyServices.httpService as HttpService;
-          const response = await httpService.request<SessionLoginResponse>({
-            method: 'POST',
-            url: '/api/auth/refresh',
-            data: { refreshToken },
+          // Use session-based token endpoint which handles auto-refresh server-side
+          const response = await httpService.request<{ accessToken: string; expiresAt: string }>({
+            method: 'GET',
+            url: `/api/session/token/${sessionId}`,
             cache: false,
+            retry: false,
           });
-          await this.handleAuthSuccess(response, 'credentials');
+
+          if (!response.accessToken) {
+            throw new Error('No access token in refresh response');
+          }
+
+          // Update access token in storage and HTTP client
+          await this.storage.setItem(STORAGE_KEYS.ACCESS_TOKEN, response.accessToken);
+          this.oxyServices.httpService.setTokens(response.accessToken);
+
+          // Update session expiry and schedule next refresh
+          if (response.expiresAt) {
+            try {
+              const session = JSON.parse(sessionJson);
+              session.expiresAt = response.expiresAt;
+              await this.storage.setItem(STORAGE_KEYS.SESSION, JSON.stringify(session));
+} catch (err) {
+              // Ignore parse errors for session update, but log for debugging.
+              console.error('AuthManager: Failed to re-save session after token refresh.', err);
+            }
+
+            if (this.config.autoRefresh) {
+              this.setupTokenRefresh(response.expiresAt);
+            }
+          }
         },
         2,    // 2 retries = 3 total attempts
         1000, // 1s base delay with exponential backoff + jitter

package/src/HttpService.ts

@@ -52,6 +52,8 @@ interface RequestConfig extends RequestOptions {
   url: string;
   data?: unknown;
   params?: Record<string, unknown>;
+  /** @internal Used to prevent infinite auth retry loops */
+  _isAuthRetry?: boolean;
 }
 
 /**
@@ -132,6 +134,7 @@ export class HttpService {
   private logger: SimpleLogger;
   private config: OxyConfig;
   private tokenRefreshPromise: Promise<string | null> | null = null;
+  private _onTokenRefreshed: ((accessToken: string) => void) | null = null;
 
   // Performance monitoring
   private requestMetrics = {
@@ -322,10 +325,27 @@ export class HttpService {
 
         // Handle response
         if (!response.ok) {
-          if (response.status === 401) {
+          // On 401, attempt token refresh and retry once before giving up
+          if (response.status === 401 && !config._isAuthRetry) {
+            const currentToken = this.tokenStore.getAccessToken();
+            if (currentToken) {
+              try {
+                const decoded = jwtDecode<JwtPayload>(currentToken);
+                if (decoded.sessionId) {
+                  const refreshResult = await this._refreshTokenFromSession(decoded.sessionId);
+                  if (refreshResult) {
+                    // Retry the request with the new token
+                    return this.request<T>({ ...config, _isAuthRetry: true, retry: false });
+                  }
+                }
+              } catch {
+                // Token decode failed, fall through to clear
+              }
+            }
+            // Refresh failed or no token — clear tokens
             this.tokenStore.clearTokens();
           }
-          
+
           // Try to parse error response (handle empty/malformed JSON)
           let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
           const contentType = response.headers.get('content-type');
@@ -343,10 +363,10 @@ export class HttpService {
               this.logger.warn('Failed to parse error response JSON:', parseError);
             }
           }
-          
-          const error = new Error(errorMessage) as Error & { 
-            status?: number; 
-            response?: { status: number; statusText: string } 
+
+          const error = new Error(errorMessage) as Error & {
+            status?: number;
+            response?: { status: number; statusText: string }
           };
           error.status = response.status;
           error.response = { status: response.status, statusText: response.statusText };
@@ -596,6 +616,7 @@ export class HttpService {
       if (response.ok) {
         const { accessToken: newToken } = await response.json();
         this.tokenStore.setTokens(newToken);
+        this._onTokenRefreshed?.(newToken);
         this.logger.debug('Token refreshed');
         return `Bearer ${newToken}`;
       }
@@ -712,6 +733,10 @@ export class HttpService {
     this.tokenStore.setTokens(accessToken, refreshToken);
   }
 
+  set onTokenRefreshed(callback: ((accessToken: string) => void) | null) {
+    this._onTokenRefreshed = callback;
+  }
+
   clearTokens(): void {
     this.tokenStore.clearTokens();
     this.tokenStore.clearCsrfToken();