@oxyhq/core 1.2.5 → 1.3.0

package/dist/cjs/mixins/OxyServices.auth.js

@@ -6,6 +6,66 @@ function OxyServicesAuthMixin(Base) {
     return class extends Base {
         constructor(...args) {
             super(...args);
+            /** @internal */ this._serviceToken = null;
+            /** @internal */ this._serviceTokenExp = 0;
+            /** @internal */ this._serviceApiKey = null;
+            /** @internal */ this._serviceApiSecret = null;
+        }
+        /**
+         * Configure service credentials for internal service-to-service communication.
+         * Call this once at startup so that getServiceToken() and makeServiceRequest()
+         * can automatically obtain and refresh tokens.
+         *
+         * @param apiKey - DeveloperApp API key (oxy_dk_*)
+         * @param apiSecret - DeveloperApp API secret
+         */
+        configureServiceAuth(apiKey, apiSecret) {
+            this._serviceApiKey = apiKey;
+            this._serviceApiSecret = apiSecret;
+            // Invalidate any cached token
+            this._serviceToken = null;
+            this._serviceTokenExp = 0;
+        }
+        /**
+         * Get a service token for internal service-to-service communication.
+         * Tokens are short-lived (1h) and automatically cached/refreshed.
+         *
+         * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
+         * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
+         */
+        async getServiceToken(apiKey, apiSecret) {
+            const key = apiKey || this._serviceApiKey;
+            const secret = apiSecret || this._serviceApiSecret;
+            if (!key || !secret) {
+                throw new Error('Service credentials not provided. Call configureServiceAuth() or pass apiKey and apiSecret.');
+            }
+            // Return cached token if still valid (with 60s buffer)
+            if (this._serviceToken && this._serviceTokenExp > Date.now() + 60000) {
+                return this._serviceToken;
+            }
+            const response = await this.makeRequest('POST', '/api/auth/service-token', { apiKey: key, apiSecret: secret }, { cache: false, retry: false });
+            this._serviceToken = response.token;
+            this._serviceTokenExp = Date.now() + response.expiresIn * 1000;
+            return this._serviceToken;
+        }
+        /**
+         * Make an authenticated request on behalf of a user using a service token.
+         * Automatically obtains/refreshes the service token.
+         *
+         * @param method - HTTP method
+         * @param url - API endpoint URL
+         * @param data - Request body or query params
+         * @param userId - Optional user ID to act on behalf of (sent as X-Oxy-User-Id)
+         */
+        async makeServiceRequest(method, url, data, userId) {
+            const token = await this.getServiceToken();
+            const headers = {
+                Authorization: `Bearer ${token}`,
+            };
+            if (userId) {
+                headers['X-Oxy-User-Id'] = userId;
+            }
+            return this.makeRequest(method, url, data, { headers, cache: false });
         }
         /**
          * Register a new identity with public key authentication

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

@@ -114,6 +114,35 @@ function OxyServicesUtilityMixin(Base) {
                             return onError(error);
                         return res.status(401).json(error);
                     }
+                    // Handle service tokens (internal service-to-service auth)
+                    // Service tokens are stateless JWTs with type: 'service' — no session validation needed
+                    if (decoded.type === 'service') {
+                        // Check expiration
+                        if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = { message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
+                            if (onError)
+                                return onError(error);
+                            return res.status(401).json(error);
+                        }
+                        // Read delegated user ID from header
+                        const oxyUserId = req.headers['x-oxy-user-id'];
+                        req.userId = oxyUserId || null;
+                        req.user = oxyUserId ? { id: oxyUserId } : null;
+                        req.accessToken = token;
+                        req.serviceApp = {
+                            appId: decoded.appId || '',
+                            appName: decoded.appName || 'unknown',
+                        };
+                        if (debug) {
+                            console.log(`[oxy.auth] Service token OK app=${decoded.appName} delegateUser=${oxyUserId || '(none)'}`);
+                        }
+                        return next();
+                    }
                     const userId = decoded.userId || decoded.id;
                     if (!userId) {
                         if (optional) {
@@ -326,5 +355,36 @@ function OxyServicesUtilityMixin(Base) {
                 }
             };
         }
+        /**
+         * Express.js middleware that only allows service tokens.
+         * Use this for internal-only endpoints that should not be accessible
+         * to regular users or API key consumers.
+         *
+         * @example
+         * ```typescript
+         * // Protect internal endpoints
+         * app.use('/internal', oxy.serviceAuth());
+         *
+         * app.post('/internal/trigger', (req, res) => {
+         *   console.log('Service app:', req.serviceApp);
+         *   console.log('Acting on behalf of user:', req.userId);
+         * });
+         * ```
+         */
+        serviceAuth(options = {}) {
+            const innerAuth = this.auth({ ...options });
+            return async (req, res, next) => {
+                await innerAuth(req, res, () => {
+                    if (!req.serviceApp) {
+                        return res.status(403).json({
+                            error: 'Service token required',
+                            message: 'This endpoint is only accessible to internal services',
+                            code: 'SERVICE_TOKEN_REQUIRED',
+                        });
+                    }
+                    next();
+                });
+            };
+        }
     };
 }

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

@@ -3,6 +3,66 @@ export function OxyServicesAuthMixin(Base) {
     return class extends Base {
         constructor(...args) {
             super(...args);
+            /** @internal */ this._serviceToken = null;
+            /** @internal */ this._serviceTokenExp = 0;
+            /** @internal */ this._serviceApiKey = null;
+            /** @internal */ this._serviceApiSecret = null;
+        }
+        /**
+         * Configure service credentials for internal service-to-service communication.
+         * Call this once at startup so that getServiceToken() and makeServiceRequest()
+         * can automatically obtain and refresh tokens.
+         *
+         * @param apiKey - DeveloperApp API key (oxy_dk_*)
+         * @param apiSecret - DeveloperApp API secret
+         */
+        configureServiceAuth(apiKey, apiSecret) {
+            this._serviceApiKey = apiKey;
+            this._serviceApiSecret = apiSecret;
+            // Invalidate any cached token
+            this._serviceToken = null;
+            this._serviceTokenExp = 0;
+        }
+        /**
+         * Get a service token for internal service-to-service communication.
+         * Tokens are short-lived (1h) and automatically cached/refreshed.
+         *
+         * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
+         * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
+         */
+        async getServiceToken(apiKey, apiSecret) {
+            const key = apiKey || this._serviceApiKey;
+            const secret = apiSecret || this._serviceApiSecret;
+            if (!key || !secret) {
+                throw new Error('Service credentials not provided. Call configureServiceAuth() or pass apiKey and apiSecret.');
+            }
+            // Return cached token if still valid (with 60s buffer)
+            if (this._serviceToken && this._serviceTokenExp > Date.now() + 60000) {
+                return this._serviceToken;
+            }
+            const response = await this.makeRequest('POST', '/api/auth/service-token', { apiKey: key, apiSecret: secret }, { cache: false, retry: false });
+            this._serviceToken = response.token;
+            this._serviceTokenExp = Date.now() + response.expiresIn * 1000;
+            return this._serviceToken;
+        }
+        /**
+         * Make an authenticated request on behalf of a user using a service token.
+         * Automatically obtains/refreshes the service token.
+         *
+         * @param method - HTTP method
+         * @param url - API endpoint URL
+         * @param data - Request body or query params
+         * @param userId - Optional user ID to act on behalf of (sent as X-Oxy-User-Id)
+         */
+        async makeServiceRequest(method, url, data, userId) {
+            const token = await this.getServiceToken();
+            const headers = {
+                Authorization: `Bearer ${token}`,
+            };
+            if (userId) {
+                headers['X-Oxy-User-Id'] = userId;
+            }
+            return this.makeRequest(method, url, data, { headers, cache: false });
         }
         /**
          * Register a new identity with public key authentication

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

@@ -111,6 +111,35 @@ export function OxyServicesUtilityMixin(Base) {
                             return onError(error);
                         return res.status(401).json(error);
                     }
+                    // Handle service tokens (internal service-to-service auth)
+                    // Service tokens are stateless JWTs with type: 'service' — no session validation needed
+                    if (decoded.type === 'service') {
+                        // Check expiration
+                        if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = { message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
+                            if (onError)
+                                return onError(error);
+                            return res.status(401).json(error);
+                        }
+                        // Read delegated user ID from header
+                        const oxyUserId = req.headers['x-oxy-user-id'];
+                        req.userId = oxyUserId || null;
+                        req.user = oxyUserId ? { id: oxyUserId } : null;
+                        req.accessToken = token;
+                        req.serviceApp = {
+                            appId: decoded.appId || '',
+                            appName: decoded.appName || 'unknown',
+                        };
+                        if (debug) {
+                            console.log(`[oxy.auth] Service token OK app=${decoded.appName} delegateUser=${oxyUserId || '(none)'}`);
+                        }
+                        return next();
+                    }
                     const userId = decoded.userId || decoded.id;
                     if (!userId) {
                         if (optional) {
@@ -323,5 +352,36 @@ export function OxyServicesUtilityMixin(Base) {
                 }
             };
         }
+        /**
+         * Express.js middleware that only allows service tokens.
+         * Use this for internal-only endpoints that should not be accessible
+         * to regular users or API key consumers.
+         *
+         * @example
+         * ```typescript
+         * // Protect internal endpoints
+         * app.use('/internal', oxy.serviceAuth());
+         *
+         * app.post('/internal/trigger', (req, res) => {
+         *   console.log('Service app:', req.serviceApp);
+         *   console.log('Acting on behalf of user:', req.userId);
+         * });
+         * ```
+         */
+        serviceAuth(options = {}) {
+            const innerAuth = this.auth({ ...options });
+            return async (req, res, next) => {
+                await innerAuth(req, res, () => {
+                    if (!req.serviceApp) {
+                        return res.status(403).json({
+                            error: 'Service token required',
+                            message: 'This endpoint is only accessible to internal services',
+                            code: 'SERVICE_TOKEN_REQUIRED',
+                        });
+                    }
+                    next();
+                });
+            };
+        }
     };
 }

package/dist/types/index.d.ts

@@ -23,6 +23,8 @@ export type { CrossDomainAuthOptions } from './CrossDomainAuth';
 export type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
 export type { PopupAuthOptions } from './mixins/OxyServices.popup';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
+export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
+export type { ServiceApp } from './mixins/OxyServices.utility';
 export { KeyManager, SignatureService, RecoveryPhraseService } from './crypto';
 export type { KeyPair, SignedMessage, AuthChallenge, RecoveryPhraseResult } from './crypto';
 export * from './models/interfaces';

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

@@ -29,8 +29,44 @@ export interface PublicKeyCheckResponse {
     registered: boolean;
     message: string;
 }
+export interface ServiceTokenResponse {
+    token: string;
+    expiresIn: number;
+    appName: string;
+}
 export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
+        /** @internal */ _serviceToken: string | null;
+        /** @internal */ _serviceTokenExp: number;
+        /** @internal */ _serviceApiKey: string | null;
+        /** @internal */ _serviceApiSecret: string | null;
+        /**
+         * Configure service credentials for internal service-to-service communication.
+         * Call this once at startup so that getServiceToken() and makeServiceRequest()
+         * can automatically obtain and refresh tokens.
+         *
+         * @param apiKey - DeveloperApp API key (oxy_dk_*)
+         * @param apiSecret - DeveloperApp API secret
+         */
+        configureServiceAuth(apiKey: string, apiSecret: string): void;
+        /**
+         * Get a service token for internal service-to-service communication.
+         * Tokens are short-lived (1h) and automatically cached/refreshed.
+         *
+         * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
+         * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
+         */
+        getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
+        /**
+         * Make an authenticated request on behalf of a user using a service token.
+         * Automatically obtains/refreshes the service token.
+         *
+         * @param method - HTTP method
+         * @param url - API endpoint URL
+         * @param data - Request body or query params
+         * @param userId - Optional user ID to act on behalf of (sent as X-Oxy-User-Id)
+         */
+        makeServiceRequest<R = any>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, userId?: string): Promise<R>;
         /**
          * Register a new identity with public key authentication
          * Identity is purely cryptographic - username and profile data are optional

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

@@ -1,5 +1,12 @@
 import type { ApiError } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * Service app metadata attached to requests authenticated with service tokens
+ */
+export interface ServiceApp {
+    appId: string;
+    appName: string;
+}
 /**
  * Options for oxyClient.auth() middleware
  */
@@ -80,6 +87,25 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         authSocket(options?: {
             debug?: boolean;
         }): (socket: any, next: (err?: Error) => void) => Promise<void>;
+        /**
+         * Express.js middleware that only allows service tokens.
+         * Use this for internal-only endpoints that should not be accessible
+         * to regular users or API key consumers.
+         *
+         * @example
+         * ```typescript
+         * // Protect internal endpoints
+         * app.use('/internal', oxy.serviceAuth());
+         *
+         * app.post('/internal/trigger', (req, res) => {
+         *   console.log('Service app:', req.serviceApp);
+         *   console.log('Acting on behalf of user:', req.userId);
+         * });
+         * ```
+         */
+        serviceAuth(options?: {
+            debug?: boolean;
+        }): (req: any, res: any, next: any) => Promise<void>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

package/package.json

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

package/src/index.ts

@@ -30,6 +30,8 @@ export type { CrossDomainAuthOptions } from './CrossDomainAuth';
 export type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
 export type { PopupAuthOptions } from './mixins/OxyServices.popup';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
+export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
+export type { ServiceApp } from './mixins/OxyServices.utility';
 
 // --- Crypto / Identity ---
 export { KeyManager, SignatureService, RecoveryPhraseService } from './crypto';

package/src/mixins/OxyServices.auth.ts

@@ -35,12 +35,99 @@ export interface PublicKeyCheckResponse {
   message: string;
 }
 
+export interface ServiceTokenResponse {
+  token: string;
+  expiresIn: number;
+  appName: string;
+}
+
 export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
+    /** @internal */ _serviceToken: string | null = null;
+    /** @internal */ _serviceTokenExp: number = 0;
+    /** @internal */ _serviceApiKey: string | null = null;
+    /** @internal */ _serviceApiSecret: string | null = null;
+
     constructor(...args: any[]) {
       super(...(args as [any]));
     }
 
+    /**
+     * Configure service credentials for internal service-to-service communication.
+     * Call this once at startup so that getServiceToken() and makeServiceRequest()
+     * can automatically obtain and refresh tokens.
+     *
+     * @param apiKey - DeveloperApp API key (oxy_dk_*)
+     * @param apiSecret - DeveloperApp API secret
+     */
+    configureServiceAuth(apiKey: string, apiSecret: string): void {
+      this._serviceApiKey = apiKey;
+      this._serviceApiSecret = apiSecret;
+      // Invalidate any cached token
+      this._serviceToken = null;
+      this._serviceTokenExp = 0;
+    }
+
+    /**
+     * Get a service token for internal service-to-service communication.
+     * Tokens are short-lived (1h) and automatically cached/refreshed.
+     *
+     * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
+     * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
+     */
+    async getServiceToken(apiKey?: string, apiSecret?: string): Promise<string> {
+      const key = apiKey || this._serviceApiKey;
+      const secret = apiSecret || this._serviceApiSecret;
+
+      if (!key || !secret) {
+        throw new Error('Service credentials not provided. Call configureServiceAuth() or pass apiKey and apiSecret.');
+      }
+
+      // Return cached token if still valid (with 60s buffer)
+      if (this._serviceToken && this._serviceTokenExp > Date.now() + 60_000) {
+        return this._serviceToken;
+      }
+
+      const response = await this.makeRequest<ServiceTokenResponse>(
+        'POST',
+        '/api/auth/service-token',
+        { apiKey: key, apiSecret: secret },
+        { cache: false, retry: false }
+      );
+
+      this._serviceToken = response.token;
+      this._serviceTokenExp = Date.now() + response.expiresIn * 1000;
+
+      return this._serviceToken;
+    }
+
+    /**
+     * Make an authenticated request on behalf of a user using a service token.
+     * Automatically obtains/refreshes the service token.
+     *
+     * @param method - HTTP method
+     * @param url - API endpoint URL
+     * @param data - Request body or query params
+     * @param userId - Optional user ID to act on behalf of (sent as X-Oxy-User-Id)
+     */
+    async makeServiceRequest<R = any>(
+      method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+      url: string,
+      data?: any,
+      userId?: string
+    ): Promise<R> {
+      const token = await this.getServiceToken();
+
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${token}`,
+      };
+      if (userId) {
+        headers['X-Oxy-User-Id'] = userId;
+      }
+
+      return this.makeRequest<R>(method, url, data, { headers, cache: false });
+    }
+
     /**
      * Register a new identity with public key authentication
      * Identity is purely cryptographic - username and profile data are optional

package/src/mixins/OxyServices.utility.ts

@@ -14,9 +14,20 @@ interface JwtPayload {
   userId?: string;
   id?: string;
   sessionId?: string;
+  type?: string;
+  appId?: string;
+  appName?: string;
   [key: string]: any;
 }
 
+/**
+ * Service app metadata attached to requests authenticated with service tokens
+ */
+export interface ServiceApp {
+  appId: string;
+  appName: string;
+}
+
 /**
  * Options for oxyClient.auth() middleware
  */
@@ -149,6 +160,39 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             return res.status(401).json(error);
           }
 
+          // Handle service tokens (internal service-to-service auth)
+          // Service tokens are stateless JWTs with type: 'service' — no session validation needed
+          if (decoded.type === 'service') {
+            // Check expiration
+            if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+              if (optional) {
+                req.userId = null;
+                req.user = null;
+                return next();
+              }
+              const error = { message: 'Service token expired', code: 'TOKEN_EXPIRED', status: 401 };
+              if (onError) return onError(error);
+              return res.status(401).json(error);
+            }
+
+            // Read delegated user ID from header
+            const oxyUserId = req.headers['x-oxy-user-id'] as string;
+
+            req.userId = oxyUserId || null;
+            req.user = oxyUserId ? ({ id: oxyUserId } as User) : null;
+            req.accessToken = token;
+            req.serviceApp = {
+              appId: decoded.appId || '',
+              appName: decoded.appName || 'unknown',
+            };
+
+            if (debug) {
+              console.log(`[oxy.auth] Service token OK app=${decoded.appName} delegateUser=${oxyUserId || '(none)'}`);
+            }
+
+            return next();
+          }
+
           const userId = decoded.userId || decoded.id;
           if (!userId) {
             if (optional) {
@@ -378,6 +422,38 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
         }
       };
     }
+    /**
+     * Express.js middleware that only allows service tokens.
+     * Use this for internal-only endpoints that should not be accessible
+     * to regular users or API key consumers.
+     *
+     * @example
+     * ```typescript
+     * // Protect internal endpoints
+     * app.use('/internal', oxy.serviceAuth());
+     *
+     * app.post('/internal/trigger', (req, res) => {
+     *   console.log('Service app:', req.serviceApp);
+     *   console.log('Acting on behalf of user:', req.userId);
+     * });
+     * ```
+     */
+    serviceAuth(options: { debug?: boolean } = {}) {
+      const innerAuth = this.auth({ ...options });
+
+      return async (req: any, res: any, next: any) => {
+        await innerAuth(req, res, () => {
+          if (!req.serviceApp) {
+            return res.status(403).json({
+              error: 'Service token required',
+              message: 'This endpoint is only accessible to internal services',
+              code: 'SERVICE_TOKEN_REQUIRED',
+            });
+          }
+          next();
+        });
+      };
+    }
   };
 }