@oxyhq/core 1.5.0 → 1.6.1

package/src/mixins/OxyServices.karma.ts

@@ -16,7 +16,7 @@ export function OxyServicesKarmaMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUserKarma(userId: string): Promise<any> {
       try {
-        return await this.makeRequest('GET', `/api/karma/${userId}`, undefined, {
+        return await this.makeRequest('GET', `/karma/${userId}`, undefined, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache
         });
@@ -30,7 +30,7 @@ export function OxyServicesKarmaMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async giveKarma(userId: string, amount: number, reason?: string): Promise<any> {
       try {
-        return await this.makeRequest('POST', `/api/karma/${userId}/give`, {
+        return await this.makeRequest('POST', `/karma/${userId}/give`, {
           amount,
           reason
         }, { cache: false });
@@ -46,7 +46,7 @@ export function OxyServicesKarmaMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUserKarmaTotal(userId: string): Promise<any> {
       try {
-        return await this.makeRequest('GET', `/api/karma/${userId}/total`, undefined, {
+        return await this.makeRequest('GET', `/karma/${userId}/total`, undefined, {
           cache: true,
           cacheTTL: CACHE_TIMES.MEDIUM,
         });
@@ -68,7 +68,7 @@ export function OxyServicesKarmaMixin<T extends typeof OxyServicesBase>(Base: T)
         if (limit) params.limit = limit;
         if (offset) params.offset = offset;
         
-        return await this.makeRequest('GET', `/api/karma/${userId}/history`, params, {
+        return await this.makeRequest('GET', `/karma/${userId}/history`, params, {
           cache: true,
           cacheTTL: CACHE_TIMES.MEDIUM,
         });
@@ -83,7 +83,7 @@ export function OxyServicesKarmaMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getKarmaLeaderboard(): Promise<any> {
       try {
-        return await this.makeRequest('GET', '/api/karma/leaderboard', undefined, {
+        return await this.makeRequest('GET', '/karma/leaderboard', undefined, {
           cache: true,
           cacheTTL: CACHE_TIMES.LONG,
         });
@@ -98,7 +98,7 @@ export function OxyServicesKarmaMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getKarmaRules(): Promise<any> {
       try {
-        return await this.makeRequest('GET', '/api/karma/rules', undefined, {
+        return await this.makeRequest('GET', '/karma/rules', undefined, {
           cache: true,
           cacheTTL: CACHE_TIMES.EXTRA_LONG, // Rules don't change often
         });

package/src/mixins/OxyServices.location.ts

@@ -17,7 +17,7 @@ export function OxyServicesLocationMixin<T extends typeof OxyServicesBase>(Base:
      */
     async updateLocation(latitude: number, longitude: number): Promise<any> {
       try {
-        return await this.makeRequest('POST', '/api/location', {
+        return await this.makeRequest('POST', '/location', {
           latitude,
           longitude
         }, { cache: false });
@@ -34,7 +34,7 @@ export function OxyServicesLocationMixin<T extends typeof OxyServicesBase>(Base:
     async getNearbyUsers(radius?: number): Promise<any[]> {
       try {
         const params: any = radius ? { radius } : undefined;
-        return await this.makeRequest('GET', '/api/location/nearby', params, {
+        return await this.makeRequest('GET', '/location/nearby', params, {
           cache: false, // Don't cache location data - always get fresh data
         });
       } catch (error) {

package/src/mixins/OxyServices.payment.ts

@@ -19,7 +19,7 @@ export function OxyServicesPaymentMixin<T extends typeof OxyServicesBase>(Base:
      */
     async createPayment(data: any): Promise<any> {
       try {
-        return await this.makeRequest('POST', '/api/payments', data, { cache: false });
+        return await this.makeRequest('POST', '/payments', data, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -32,7 +32,7 @@ export function OxyServicesPaymentMixin<T extends typeof OxyServicesBase>(Base:
      */
     async getPayment(paymentId: string): Promise<any> {
       try {
-        return await this.makeRequest('GET', `/api/payments/${paymentId}`, undefined, {
+        return await this.makeRequest('GET', `/payments/${paymentId}`, undefined, {
           cache: true,
           cacheTTL: CACHE_TIMES.LONG,
         });
@@ -47,7 +47,7 @@ export function OxyServicesPaymentMixin<T extends typeof OxyServicesBase>(Base:
      */
     async getUserPayments(): Promise<any[]> {
       try {
-        return await this.makeRequest('GET', '/api/payments/user', undefined, {
+        return await this.makeRequest('GET', '/payments/user', undefined, {
           cache: false, // Don't cache user payments - always get fresh data
         });
       } catch (error) {
@@ -62,7 +62,7 @@ export function OxyServicesPaymentMixin<T extends typeof OxyServicesBase>(Base:
      */
     async getSubscription(userId: string): Promise<any> {
       try {
-        return await this.makeRequest('GET', `/api/subscription/${userId}`, undefined, {
+        return await this.makeRequest('GET', `/subscription/${userId}`, undefined, {
           cache: true,
           cacheTTL: CACHE_TIMES.MEDIUM,
         });
@@ -94,7 +94,7 @@ export function OxyServicesPaymentMixin<T extends typeof OxyServicesBase>(Base:
      */
     async getWallet(userId: string): Promise<any> {
       try {
-        return await this.makeRequest('GET', `/api/wallet/${userId}`, undefined, {
+        return await this.makeRequest('GET', `/wallet/${userId}`, undefined, {
           cache: true,
           cacheTTL: CACHE_TIMES.SHORT, // Cache wallet for short time as balance changes frequently
         });
@@ -132,7 +132,7 @@ export function OxyServicesPaymentMixin<T extends typeof OxyServicesBase>(Base:
         if (options?.offset) params.append('offset', options.offset.toString());
         
         const queryString = params.toString();
-        const url = `/api/wallet/transactions/${userId}${queryString ? `?${queryString}` : ''}`;
+        const url = `/wallet/transactions/${userId}${queryString ? `?${queryString}` : ''}`;
         
         return await this.makeRequest('GET', url, undefined, {
           cache: false, // Don't cache transactions - always get fresh data

package/src/mixins/OxyServices.popup.ts

@@ -120,7 +120,7 @@ export function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBase>(Base
         try {
           const userData = await this.makeRequest<any>(
             'GET',
-            `/api/session/user/${session.sessionId}`,
+            `/session/user/${session.sessionId}`,
             undefined,
             { cache: false }
           );

package/src/mixins/OxyServices.privacy.ts

@@ -53,7 +53,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
      */
     async getBlockedUsers(): Promise<BlockedUser[]> {
       try {
-        return await this.makeRequest<BlockedUser[]>('GET', '/api/privacy/blocked', undefined, {
+        return await this.makeRequest<BlockedUser[]>('GET', '/privacy/blocked', undefined, {
           cache: true,
           cacheTTL: 1 * 60 * 1000, // 1 minute cache
         });
@@ -72,7 +72,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('POST', `/api/privacy/blocked/${userId}`, undefined, {
+        return await this.makeRequest<{ message: string }>('POST', `/privacy/blocked/${userId}`, undefined, {
           cache: false,
         });
       } catch (error) {
@@ -90,7 +90,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('DELETE', `/api/privacy/blocked/${userId}`, undefined, {
+        return await this.makeRequest<{ message: string }>('DELETE', `/privacy/blocked/${userId}`, undefined, {
           cache: false,
         });
       } catch (error) {
@@ -121,7 +121,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
      */
     async getRestrictedUsers(): Promise<RestrictedUser[]> {
       try {
-        return await this.makeRequest<RestrictedUser[]>('GET', '/api/privacy/restricted', undefined, {
+        return await this.makeRequest<RestrictedUser[]>('GET', '/privacy/restricted', undefined, {
           cache: true,
           cacheTTL: 1 * 60 * 1000, // 1 minute cache
         });
@@ -140,7 +140,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('POST', `/api/privacy/restricted/${userId}`, undefined, {
+        return await this.makeRequest<{ message: string }>('POST', `/privacy/restricted/${userId}`, undefined, {
           cache: false,
         });
       } catch (error) {
@@ -158,7 +158,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('DELETE', `/api/privacy/restricted/${userId}`, undefined, {
+        return await this.makeRequest<{ message: string }>('DELETE', `/privacy/restricted/${userId}`, undefined, {
           cache: false,
         });
       } catch (error) {

package/src/mixins/OxyServices.security.ts

@@ -31,7 +31,7 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
 
         const response = await this.makeRequest<SecurityActivityResponse>(
           'GET',
-          '/api/security/activity',
+          '/security/activity',
           params,
           { cache: false }
         );
@@ -65,7 +65,7 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
       try {
         await this.makeRequest<{ success: boolean }>(
           'POST',
-          '/api/security/activity/private-key-exported',
+          '/security/activity/private-key-exported',
           { deviceId },
           { cache: false }
         );
@@ -87,7 +87,7 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
       try {
         await this.makeRequest<{ success: boolean }>(
           'POST',
-          '/api/security/activity/backup-created',
+          '/security/activity/backup-created',
           { deviceId },
           { cache: false }
         );

package/src/mixins/OxyServices.user.ts

@@ -15,7 +15,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getProfileByUsername(username: string): Promise<User> {
       try {
-        return await this.makeRequest<User>('GET', `/api/profiles/username/${username}`, undefined, {
+        return await this.makeRequest<User>('GET', `/profiles/username/${username}`, undefined, {
           cache: true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache for profiles
         });
@@ -35,7 +35,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
         const response = await this.makeRequest<SearchProfilesResponse | User[]>(
           'GET',
-          '/api/profiles/search',
+          '/profiles/search',
           paramsObj,
           {
             cache: true,
@@ -97,7 +97,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       [key: string]: any;
     }>> {
       return this.withAuthRetry(async () => {
-        return await this.makeRequest('GET', '/api/profiles/recommendations', undefined, { cache: true });
+        return await this.makeRequest('GET', '/profiles/recommendations', undefined, { cache: true });
       }, 'getProfileRecommendations');
     }
 
@@ -106,7 +106,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUserById(userId: string): Promise<User> {
       try {
-        return await this.makeRequest<User>('GET', `/api/users/${userId}`, undefined, {
+        return await this.makeRequest<User>('GET', `/users/${userId}`, undefined, {
           cache: true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache
         });
@@ -120,7 +120,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getCurrentUser(): Promise<User> {
       return this.withAuthRetry(async () => {
-        return await this.makeRequest<User>('GET', '/api/users/me', undefined, {
+        return await this.makeRequest<User>('GET', '/users/me', undefined, {
           cache: true,
           cacheTTL: 1 * 60 * 1000, // 1 minute cache for current user
         });
@@ -133,7 +133,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async updateProfile(updates: Record<string, any>): Promise<User> {
       try {
-        return await this.makeRequest<User>('PUT', '/api/users/me', updates, { cache: false });
+        return await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false });
       } catch (error) {
         const errorAny = error as any;
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -162,7 +162,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     async getPrivacySettings(userId?: string): Promise<any> {
       try {
         const id = userId || (await this.getCurrentUser()).id;
-        return await this.makeRequest<any>('GET', `/api/privacy/${id}/privacy`, undefined, {
+        return await this.makeRequest<any>('GET', `/privacy/${id}/privacy`, undefined, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache
         });
@@ -179,7 +179,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     async updatePrivacySettings(settings: Record<string, any>, userId?: string): Promise<any> {
       try {
         const id = userId || (await this.getCurrentUser()).id;
-        return await this.makeRequest<any>('PATCH', `/api/privacy/${id}/privacy`, settings, {
+        return await this.makeRequest<any>('PATCH', `/privacy/${id}/privacy`, settings, {
           cache: false,
         });
       } catch (error) {
@@ -192,7 +192,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async requestAccountVerification(reason: string, evidence?: string): Promise<{ message: string; requestId: string }> {
       try {
-        return await this.makeRequest<{ message: string; requestId: string }>('POST', '/api/users/verify/request', {
+        return await this.makeRequest<{ message: string; requestId: string }>('POST', '/users/verify/request', {
           reason,
           evidence,
         }, { cache: false });
@@ -209,7 +209,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         // Use httpService for blob responses (it handles blob responses automatically)
         const result = await this.getClient().request<Blob>({
           method: 'GET',
-          url: `/api/users/me/data`,
+          url: `/users/me/data`,
           params: { format },
           cache: false,
         });
@@ -227,7 +227,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async deleteAccount(password: string, confirmText: string): Promise<{ message: string }> {
       try {
-        return await this.makeRequest<{ message: string }>('DELETE', '/api/users/me', {
+        return await this.makeRequest<{ message: string }>('DELETE', '/users/me', {
           password,
           confirmText,
         }, { cache: false });
@@ -242,7 +242,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async followUser(userId: string): Promise<{ success: boolean; message: string }> {
       try {
-        return await this.makeRequest('POST', `/api/users/${userId}/follow`, undefined, { cache: false });
+        return await this.makeRequest('POST', `/users/${userId}/follow`, undefined, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -253,7 +253,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async unfollowUser(userId: string): Promise<{ success: boolean; message: string }> {
       try {
-        return await this.makeRequest('DELETE', `/api/users/${userId}/follow`, undefined, { cache: false });
+        return await this.makeRequest('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -264,7 +264,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getFollowStatus(userId: string): Promise<{ isFollowing: boolean }> {
       try {
-        return await this.makeRequest('GET', `/api/users/${userId}/follow-status`, undefined, {
+        return await this.makeRequest('GET', `/users/${userId}/follow-status`, undefined, {
           cache: true,
           cacheTTL: 1 * 60 * 1000, // 1 minute cache
         });
@@ -282,7 +282,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     ): Promise<{ followers: User[]; total: number; hasMore: boolean }> {
       try {
         const params = buildPaginationParams(pagination || {});
-        const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('GET', `/api/users/${userId}/followers`, params, {
+        const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('GET', `/users/${userId}/followers`, params, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache
         });
@@ -305,7 +305,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     ): Promise<{ following: User[]; total: number; hasMore: boolean }> {
       try {
         const params = buildPaginationParams(pagination || {});
-        const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('GET', `/api/users/${userId}/following`, params, {
+        const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('GET', `/users/${userId}/following`, params, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache
         });
@@ -324,7 +324,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getNotifications(): Promise<Notification[]> {
       return this.withAuthRetry(async () => {
-        return await this.makeRequest<Notification[]>('GET', '/api/notifications', undefined, {
+        return await this.makeRequest<Notification[]>('GET', '/notifications', undefined, {
           cache: false, // Don't cache notifications - always get fresh data
         });
       }, 'getNotifications');
@@ -335,7 +335,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUnreadCount(): Promise<number> {
       try {
-        const res = await this.makeRequest<{ count: number }>('GET', '/api/notifications/unread-count', undefined, {
+        const res = await this.makeRequest<{ count: number }>('GET', '/notifications/unread-count', undefined, {
           cache: false, // Don't cache unread count - always get fresh data
         });
         return res.count;
@@ -349,7 +349,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async createNotification(data: Partial<Notification>): Promise<Notification> {
       try {
-        return await this.makeRequest<Notification>('POST', '/api/notifications', data, { cache: false });
+        return await this.makeRequest<Notification>('POST', '/notifications', data, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -360,7 +360,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async markNotificationAsRead(notificationId: string): Promise<void> {
       try {
-        await this.makeRequest('PUT', `/api/notifications/${notificationId}/read`, undefined, { cache: false });
+        await this.makeRequest('PUT', `/notifications/${notificationId}/read`, undefined, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -371,7 +371,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async markAllNotificationsAsRead(): Promise<void> {
       try {
-        await this.makeRequest('PUT', '/api/notifications/read-all', undefined, { cache: false });
+        await this.makeRequest('PUT', '/notifications/read-all', undefined, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -382,7 +382,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async deleteNotification(notificationId: string): Promise<void> {
       try {
-        await this.makeRequest('DELETE', `/api/notifications/${notificationId}`, undefined, { cache: false });
+        await this.makeRequest('DELETE', `/notifications/${notificationId}`, undefined, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.utility.ts

@@ -68,7 +68,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
           title: string;
           description: string;
           image?: string;
-        }>('GET', '/api/link-metadata', { url }, {
+        }>('GET', '/link-metadata', { url }, {
           cache: true,
           cacheTTL: CACHE_TIMES.EXTRA_LONG,
         });
@@ -83,25 +83,36 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * Validates JWT tokens against the Oxy API and attaches user data to requests.
      * Uses server-side session validation for security (not just JWT decode).
      *
+     * **Design note — jwtDecode vs jwt.verify:**
+     * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
+     * verification) for user tokens. This is by design, NOT a security gap:
+     * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
+     * - Security comes from API-based session validation (`validateSession()`)
+     *   which checks the session server-side on every request
+     * - Service tokens (type: 'service') DO use cryptographic HMAC verification
+     *   via the `jwtSecret` option, since they are stateless
+     * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
+     *   direct access to `ACCESS_TOKEN_SECRET`
+     *
      * @example
      * ```typescript
      * import { OxyServices } from '@oxyhq/core';
      *
      * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
      *
-     * // Protect all routes under /api/protected
-     * app.use('/api/protected', oxy.auth());
+     * // Protect all routes under /protected
+     * app.use('/protected', oxy.auth());
      *
      * // Access user in route handler
-     * app.get('/api/protected/me', (req, res) => {
+     * app.get('/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 }));
+     * app.use('/admin', oxy.auth({ loadUser: true }));
      *
      * // Optional auth - attach user if present, don't block if absent
-     * app.use('/api/public', oxy.auth({ optional: true }));
+     * app.use('/public', oxy.auth({ optional: true }));
      * ```
      *
      * @param options Optional configuration
@@ -138,6 +149,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'MISSING_TOKEN',
               message: 'Access token required',
               code: 'MISSING_TOKEN',
               status: 401
@@ -158,6 +170,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'INVALID_TOKEN_FORMAT',
               message: 'Invalid token format',
               code: 'INVALID_TOKEN_FORMAT',
               status: 401
@@ -177,6 +190,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 return next();
               }
               const error = {
+                error: 'SERVICE_TOKEN_NOT_CONFIGURED',
                 message: 'Service token verification not configured',
                 code: 'SERVICE_TOKEN_NOT_CONFIGURED',
                 status: 403
@@ -206,13 +220,23 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
                 throw new Error('Invalid signature');
               }
-            } catch {
+            } catch (verifyError) {
+              const isSignatureError = verifyError instanceof Error &&
+                (verifyError.message === 'Invalid signature' || verifyError.message === 'Invalid token structure');
+
+              if (!isSignatureError) {
+                console.error('[oxy.auth] Unexpected error during service token verification:', verifyError);
+                const error = { error: 'AUTH_INTERNAL_ERROR', message: 'Internal authentication error', code: 'AUTH_INTERNAL_ERROR', status: 500 };
+                if (onError) return onError(error);
+                return res.status(500).json(error);
+              }
+
               if (optional) {
                 req.userId = null;
                 req.user = null;
                 return next();
               }
-              const error = { message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+              const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
@@ -224,7 +248,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 req.user = null;
                 return next();
               }
-              const error = { message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
+              const error = { error: 'TOKEN_EXPIRED', message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
@@ -236,7 +260,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 req.user = null;
                 return next();
               }
-              const error = { message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+              const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
@@ -268,6 +292,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'INVALID_TOKEN_PAYLOAD',
               message: 'Token missing user ID',
               code: 'INVALID_TOKEN_PAYLOAD',
               status: 401
@@ -285,6 +310,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
 
             const error = {
+              error: 'TOKEN_EXPIRED',
               message: 'Token expired',
               code: 'TOKEN_EXPIRED',
               status: 401
@@ -309,6 +335,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 }
 
                 const error = {
+                  error: 'INVALID_SESSION',
                   message: 'Session invalid or expired',
                   code: 'INVALID_SESSION',
                   status: 401
@@ -346,6 +373,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               }
 
               const error = {
+                error: 'SESSION_VALIDATION_ERROR',
                 message: 'Session validation failed',
                 code: 'SESSION_VALIDATION_ERROR',
                 status: 401
@@ -406,6 +434,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * Returns a middleware function for Socket.IO that validates JWT tokens
      * from the handshake auth object and attaches user data to the socket.
      *
+     * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
+     *
      * @example
      * ```typescript
      * import { OxyServices } from '@oxyhq/core';
@@ -504,7 +534,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * });
      * ```
      */
-    serviceAuth(options: { debug?: boolean } = {}) {
+    serviceAuth(options: { debug?: boolean; jwtSecret?: string } = {}) {
       const innerAuth = this.auth({ ...options });
 
       return async (req: any, res: any, next: any) => {