@oxyhq/core 1.2.5 → 1.4.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

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OxyServicesUtilityMixin = OxyServicesUtilityMixin;
 /**
@@ -59,7 +92,7 @@ function OxyServicesUtilityMixin(Base) {
          * @returns Express middleware function
          */
         auth(options = {}) {
-            const { debug = false, onError, loadUser = false, optional = false } = options;
+            const { debug = false, onError, loadUser = false, optional = false, jwtSecret } = options;
             // Cast to any for cross-mixin method access (Auth mixin methods available at runtime)
             const oxyInstance = this;
             // Return an async middleware function
@@ -114,6 +147,95 @@ 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' — requires signature verification
+                    if (decoded.type === 'service') {
+                        // Service tokens MUST be cryptographically verified — reject if no secret provided
+                        if (!jwtSecret) {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = {
+                                message: 'Service token verification not configured',
+                                code: 'SERVICE_TOKEN_NOT_CONFIGURED',
+                                status: 403
+                            };
+                            if (onError)
+                                return onError(error);
+                            return res.status(403).json(error);
+                        }
+                        // Verify JWT signature (not just decode)
+                        try {
+                            const { createHmac } = await Promise.resolve().then(() => __importStar(require('crypto')));
+                            const [headerB64, payloadB64, signatureB64] = token.split('.');
+                            if (!headerB64 || !payloadB64 || !signatureB64) {
+                                throw new Error('Invalid token structure');
+                            }
+                            const expectedSig = createHmac('sha256', jwtSecret)
+                                .update(`${headerB64}.${payloadB64}`)
+                                .digest('base64')
+                                .replace(/\+/g, '-')
+                                .replace(/\//g, '_')
+                                .replace(/=/g, '');
+                            // Timing-safe comparison
+                            const sigBuf = Buffer.from(signatureB64);
+                            const expectedBuf = Buffer.from(expectedSig);
+                            const { timingSafeEqual } = await Promise.resolve().then(() => __importStar(require('crypto')));
+                            if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
+                                throw new Error('Invalid signature');
+                            }
+                        }
+                        catch {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = { message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+                            if (onError)
+                                return onError(error);
+                            return res.status(401).json(error);
+                        }
+                        // 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);
+                        }
+                        // Validate required service token fields
+                        if (!decoded.appId) {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = { message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', 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 +448,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

@@ -56,7 +56,7 @@ export function OxyServicesUtilityMixin(Base) {
          * @returns Express middleware function
          */
         auth(options = {}) {
-            const { debug = false, onError, loadUser = false, optional = false } = options;
+            const { debug = false, onError, loadUser = false, optional = false, jwtSecret } = options;
             // Cast to any for cross-mixin method access (Auth mixin methods available at runtime)
             const oxyInstance = this;
             // Return an async middleware function
@@ -111,6 +111,95 @@ 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' — requires signature verification
+                    if (decoded.type === 'service') {
+                        // Service tokens MUST be cryptographically verified — reject if no secret provided
+                        if (!jwtSecret) {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = {
+                                message: 'Service token verification not configured',
+                                code: 'SERVICE_TOKEN_NOT_CONFIGURED',
+                                status: 403
+                            };
+                            if (onError)
+                                return onError(error);
+                            return res.status(403).json(error);
+                        }
+                        // Verify JWT signature (not just decode)
+                        try {
+                            const { createHmac } = await import('crypto');
+                            const [headerB64, payloadB64, signatureB64] = token.split('.');
+                            if (!headerB64 || !payloadB64 || !signatureB64) {
+                                throw new Error('Invalid token structure');
+                            }
+                            const expectedSig = createHmac('sha256', jwtSecret)
+                                .update(`${headerB64}.${payloadB64}`)
+                                .digest('base64')
+                                .replace(/\+/g, '-')
+                                .replace(/\//g, '_')
+                                .replace(/=/g, '');
+                            // Timing-safe comparison
+                            const sigBuf = Buffer.from(signatureB64);
+                            const expectedBuf = Buffer.from(expectedSig);
+                            const { timingSafeEqual } = await import('crypto');
+                            if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
+                                throw new Error('Invalid signature');
+                            }
+                        }
+                        catch {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = { message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+                            if (onError)
+                                return onError(error);
+                            return res.status(401).json(error);
+                        }
+                        // 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);
+                        }
+                        // Validate required service token fields
+                        if (!decoded.appId) {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
+                            }
+                            const error = { message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', 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 +412,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
  */
@@ -12,6 +19,12 @@ interface AuthMiddlewareOptions {
     loadUser?: boolean;
     /** Optional auth - attach user if token present but don't block (default: false) */
     optional?: boolean;
+    /**
+     * JWT secret for verifying service token signatures locally.
+     * When provided, service tokens will be cryptographically verified.
+     * When omitted, service tokens will be rejected (secure default).
+     */
+    jwtSecret?: string;
 }
 export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -80,6 +93,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.4.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
  */
@@ -29,6 +40,12 @@ interface AuthMiddlewareOptions {
   loadUser?: boolean;
   /** Optional auth - attach user if token present but don't block (default: false) */
   optional?: boolean;
+  /**
+   * JWT secret for verifying service token signatures locally.
+   * When provided, service tokens will be cryptographically verified.
+   * When omitted, service tokens will be rejected (secure default).
+   */
+  jwtSecret?: string;
 }
 
 export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base: T) {
@@ -91,7 +108,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * @returns Express middleware function
      */
     auth(options: AuthMiddlewareOptions = {}) {
-      const { debug = false, onError, loadUser = false, optional = false } = options;
+      const { debug = false, onError, loadUser = false, optional = false, jwtSecret } = options;
       // Cast to any for cross-mixin method access (Auth mixin methods available at runtime)
       const oxyInstance = this as any;
 
@@ -149,6 +166,99 @@ 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' — requires signature verification
+          if (decoded.type === 'service') {
+            // Service tokens MUST be cryptographically verified — reject if no secret provided
+            if (!jwtSecret) {
+              if (optional) {
+                req.userId = null;
+                req.user = null;
+                return next();
+              }
+              const error = {
+                message: 'Service token verification not configured',
+                code: 'SERVICE_TOKEN_NOT_CONFIGURED',
+                status: 403
+              };
+              if (onError) return onError(error);
+              return res.status(403).json(error);
+            }
+
+            // Verify JWT signature (not just decode)
+            try {
+              const { createHmac } = await import('crypto');
+              const [headerB64, payloadB64, signatureB64] = token.split('.');
+              if (!headerB64 || !payloadB64 || !signatureB64) {
+                throw new Error('Invalid token structure');
+              }
+              const expectedSig = createHmac('sha256', jwtSecret)
+                .update(`${headerB64}.${payloadB64}`)
+                .digest('base64')
+                .replace(/\+/g, '-')
+                .replace(/\//g, '_')
+                .replace(/=/g, '');
+
+              // Timing-safe comparison
+              const sigBuf = Buffer.from(signatureB64);
+              const expectedBuf = Buffer.from(expectedSig);
+              const { timingSafeEqual } = await import('crypto');
+              if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
+                throw new Error('Invalid signature');
+              }
+            } catch {
+              if (optional) {
+                req.userId = null;
+                req.user = null;
+                return next();
+              }
+              const error = { message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+              if (onError) return onError(error);
+              return res.status(401).json(error);
+            }
+
+            // 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);
+            }
+
+            // Validate required service token fields
+            if (!decoded.appId) {
+              if (optional) {
+                req.userId = null;
+                req.user = null;
+                return next();
+              }
+              const error = { message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', 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 +488,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();
+        });
+      };
+    }
   };
 }