@oxyhq/core 1.11.12 → 1.11.14

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

@@ -5,13 +5,58 @@
  * and Express.js authentication middleware
  */
 import { jwtDecode } from 'jwt-decode';
+import { loadNodeCrypto } from '../utils/platformCrypto.js';
+import { logger } from '../utils/loggerUtils.js';
 import { CACHE_TIMES } from './mixinHelpers.js';
+/**
+ * Expected JWT audience for tokens issued by the Oxy auth service.
+ */
+const OXY_JWT_AUDIENCE = 'oxy-api';
+/**
+ * Expected JWT issuer for tokens issued by the Oxy auth service.
+ */
+const OXY_JWT_ISSUER = 'oxy-auth';
+/**
+ * Sentinel error classes for service-token verification. Using classes (not
+ * message strings) makes the catch site below safe to extend: a new failure
+ * mode added later cannot silently fall through to the generic 500 branch.
+ */
+class ServiceTokenStructureError extends Error {
+    constructor(message = 'Service token has malformed structure') {
+        super(message);
+        this.name = 'ServiceTokenStructureError';
+    }
+}
+class ServiceTokenSignatureError extends Error {
+    constructor(message = 'Service token signature is invalid') {
+        super(message);
+        this.name = 'ServiceTokenSignatureError';
+    }
+}
+class ServiceTokenClaimError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServiceTokenClaimError';
+    }
+}
 export function OxyServicesUtilityMixin(Base) {
     return class extends Base {
+        // TypeScript's mixin pattern requires `(...args: any[])` here — the
+        // constructor signature is a structural shape check the compiler enforces.
+        // Matches every other mixin in this package; do not change without a
+        // monorepo-wide refactor of the mixin pipeline.
         constructor(...args) {
             super(...args);
             /** @internal In-memory cache for acting-as verification results (TTL: 5 min) */
             this._actingAsCache = new Map();
+            /**
+             * In-memory cache for service-acting-as verification.
+             * Negative results are cached for 1min to avoid hammering the verify
+             * endpoint when a service is misconfigured; positive grants are cached
+             * for 5min to amortize the round-trip without holding stale grants too long.
+             * @internal
+             */
+            this._serviceActingAsCache = new Map();
         }
         /**
          * Verify that a user is authorized to act as a managed account.
@@ -37,7 +82,13 @@ export function OxyServicesUtilityMixin(Base) {
                 });
                 return result && result.authorized ? result : null;
             }
-            catch {
+            catch (error) {
+                logger.warn('[oxy.auth] verifyActingAs lookup failed — caching negative result', {
+                    component: 'auth',
+                    method: 'verifyActingAs',
+                    userId,
+                    accountId,
+                }, error);
                 // Cache negative result for 1 minute to avoid hammering on transient errors
                 this._actingAsCache.set(cacheKey, {
                     result: null,
@@ -46,6 +97,53 @@ export function OxyServicesUtilityMixin(Base) {
                 return null;
             }
         }
+        /**
+         * Verify that a service app holds an active delegation grant authorising
+         * it to act on behalf of `userId`. Returns the grant (with allowed scopes)
+         * on success or `null` if no valid grant exists. Negative answers are
+         * cached briefly to protect the verify endpoint from misconfigured callers.
+         *
+         * Implemented as a per-instance Map keyed by `appId:userId`. Cached
+         * positive grants live for 5 minutes (acceptable staleness window for an
+         * impersonation grant); revocations propagate within that window.
+         *
+         * @internal Used by the auth() middleware — not part of the public API
+         */
+        async verifyServiceActingAs(appId, userId) {
+            const cacheKey = `${appId}:${userId}`;
+            const now = Date.now();
+            const cached = this._serviceActingAsCache.get(cacheKey);
+            if (cached && cached.expiresAt > now) {
+                return cached.result;
+            }
+            try {
+                const result = await this.makeRequest('GET', '/internal/service-acting-as/verify', { appId, userId }, { cache: false, retry: false, timeout: 5000 });
+                const authorized = Boolean(result && result.authorized);
+                const verified = authorized
+                    ? { authorized: true, scopes: Array.isArray(result.scopes) ? result.scopes : [] }
+                    : null;
+                this._serviceActingAsCache.set(cacheKey, {
+                    result: verified,
+                    expiresAt: now + 5 * 60 * 1000,
+                });
+                return verified;
+            }
+            catch (error) {
+                logger.warn('[oxy.auth] verifyServiceActingAs lookup failed — caching negative result', {
+                    component: 'auth',
+                    method: 'verifyServiceActingAs',
+                    appId,
+                    userId,
+                }, error);
+                // Negative cache prevents a runaway loop if the verify endpoint is
+                // down, while still letting a real grant become visible within 60s.
+                this._serviceActingAsCache.set(cacheKey, {
+                    result: null,
+                    expiresAt: now + 1 * 60 * 1000,
+                });
+                return null;
+            }
+        }
         /**
          * Fetch link metadata
          */
@@ -73,9 +171,17 @@ export function OxyServicesUtilityMixin(Base) {
          * - 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
+         *   via the `jwtSecret` option, since they are stateless. Service tokens
+         *   are additionally checked for `aud`, `iss`, and `type` claims to prevent
+         *   cross-token-type confusion attacks.
          * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
-         *   direct access to `ACCESS_TOKEN_SECRET`
+         *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
+         *
+         * **Service-token delegation (X-Oxy-User-Id):**
+         * When a service token is accompanied by `X-Oxy-User-Id`, the SDK calls
+         * `verifyServiceActingAs(appId, userId)` to confirm an explicit delegation
+         * grant exists before attaching `req.userId`. A missing/expired grant
+         * results in a 403 — there is no fail-open path.
          *
          * @example
          * ```typescript
@@ -84,7 +190,7 @@ export function OxyServicesUtilityMixin(Base) {
          * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
          *
          * // Protect all routes under /protected
-         * app.use('/protected', oxy.auth());
+         * app.use('/protected', oxy.auth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
          *
          * // Access user in route handler
          * app.get('/protected/me', (req, res) => {
@@ -96,14 +202,18 @@ export function OxyServicesUtilityMixin(Base) {
          *
          * // Optional auth - attach user if present, don't block if absent
          * app.use('/public', oxy.auth({ optional: true }));
+         *
+         * // Require a specific scope on a service-token-protected route
+         * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }), oxy.requireScope('files:write'));
          * ```
          *
          * @param options Optional configuration
          * @returns Express middleware function
          */
         auth(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 { debug = false, onError, loadUser = false, optional = false, jwtSecret, expectedIssuer = OXY_JWT_ISSUER, expectedAudience = OXY_JWT_AUDIENCE, } = options;
+            // Cross-mixin method access: typed as a structural subset of the
+            // composed OxyServices we know we have at runtime.
             const oxyInstance = this;
             // Return an async middleware function
             return async (req, res, next) => {
@@ -113,9 +223,12 @@ export function OxyServicesUtilityMixin(Base) {
                 // the managed account, preserving the original user for audit trails.
                 const processActingAs = async () => {
                     const actingAsUserId = req.headers['x-acting-as'];
-                    if (!actingAsUserId)
+                    if (!actingAsUserId || typeof actingAsUserId !== 'string')
                         return true; // No header, proceed normally
-                    const verification = await oxyInstance.verifyActingAs(req.userId, actingAsUserId);
+                    const currentUserId = req.userId;
+                    if (!currentUserId)
+                        return true; // No authenticated user yet — nothing to swap
+                    const verification = await oxyInstance.verifyActingAs(currentUserId, actingAsUserId);
                     if (!verification) {
                         const error = {
                             error: 'ACTING_AS_UNAUTHORIZED',
@@ -132,23 +245,25 @@ export function OxyServicesUtilityMixin(Base) {
                         return false;
                     }
                     // Preserve original user for audit trails
-                    req.originalUser = { id: req.userId, ...req.user };
+                    req.originalUser = { id: currentUserId, ...(req.user ?? {}) };
                     req.actingAs = { userId: actingAsUserId, role: verification.role };
                     // Swap user identity to the managed account
                     req.userId = actingAsUserId;
-                    req.user = { id: actingAsUserId };
-                    // Also set _id for routes that use Pattern B (req.user._id)
-                    if (req.user) {
-                        req.user._id = actingAsUserId;
-                    }
+                    req.user = { id: actingAsUserId, _id: actingAsUserId };
                     if (debug) {
-                        console.log(`[oxy.auth] Acting as ${actingAsUserId} (role=${verification.role}) original=${req.originalUser.id}`);
+                        logger.debug(`[oxy.auth] Acting as ${actingAsUserId} (role=${verification.role}) original=${currentUserId}`, {
+                            component: 'auth',
+                            method: 'auth.processActingAs',
+                        });
                     }
                     return true;
                 };
                 try {
-                    // Extract token from Authorization header or query params
-                    const authHeader = req.headers['authorization'];
+                    // Extract token from Authorization header or query params.
+                    // Node/Express normalizes `Authorization` to a string; we guard
+                    // against the (legal but unusual) string[] case anyway.
+                    const rawAuthHeader = req.headers.authorization;
+                    const authHeader = Array.isArray(rawAuthHeader) ? rawAuthHeader[0] : rawAuthHeader;
                     let token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
                     // Fallback to query params (useful for WebSocket upgrades)
                     if (!token) {
@@ -159,7 +274,10 @@ export function OxyServicesUtilityMixin(Base) {
                             token = q.access_token;
                     }
                     if (debug) {
-                        console.log(`[oxy.auth] ${req.method} ${req.path} | token: ${!!token}`);
+                        logger.debug(`[oxy.auth] ${req.method} ${req.path} | token: ${!!token}`, {
+                            component: 'auth',
+                            method: 'auth',
+                        });
                     }
                     if (!token) {
                         if (optional) {
@@ -183,6 +301,12 @@ export function OxyServicesUtilityMixin(Base) {
                         decoded = jwtDecode(token);
                     }
                     catch (decodeError) {
+                        if (debug) {
+                            logger.debug('[oxy.auth] Token decode failed', {
+                                component: 'auth',
+                                method: 'auth',
+                            }, decodeError);
+                        }
                         if (optional) {
                             req.userId = null;
                             req.user = null;
@@ -218,49 +342,72 @@ export function OxyServicesUtilityMixin(Base) {
                                 return onError(error);
                             return res.status(403).json(error);
                         }
-                        // Verify JWT signature (not just decode)
+                        // Verify JWT signature, then audience / issuer / type / appId claims.
+                        //
+                        // Signature verification uses a manual HMAC-SHA256 compare because
+                        // this file ships into RN/web bundles where `jsonwebtoken` is
+                        // unavailable. The middleware only ever runs on Node hosts (see
+                        // platformCrypto's doc-comment), and `loadNodeCrypto` is per-
+                        // platform: the RN variant throws so Metro never bundles a Node
+                        // built-in reference.
                         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');
-                            }
+                            await verifyServiceTokenSignature(token, jwtSecret);
+                            verifyServiceTokenClaims(decoded, {
+                                audience: expectedAudience,
+                                issuer: expectedIssuer,
+                            });
                         }
                         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 };
+                            // Structure + signature + claim errors all map to 401. Anything
+                            // else (e.g. Node crypto failing to load on a misconfigured host)
+                            // genuinely IS a 500.
+                            if (verifyError instanceof ServiceTokenStructureError ||
+                                verifyError instanceof ServiceTokenSignatureError ||
+                                verifyError instanceof ServiceTokenClaimError) {
+                                if (debug) {
+                                    logger.debug('[oxy.auth] Service token rejected', {
+                                        component: 'auth',
+                                        method: 'auth.serviceToken',
+                                        reason: verifyError.name,
+                                        detail: verifyError.message,
+                                    });
+                                }
+                                if (optional) {
+                                    req.userId = null;
+                                    req.user = null;
+                                    return next();
+                                }
+                                const code = verifyError instanceof ServiceTokenSignatureError
+                                    ? 'INVALID_SERVICE_TOKEN'
+                                    : verifyError instanceof ServiceTokenStructureError
+                                        ? 'INVALID_SERVICE_TOKEN'
+                                        : 'INVALID_SERVICE_TOKEN_CLAIMS';
+                                const error = {
+                                    error: code,
+                                    message: verifyError.message,
+                                    code,
+                                    status: 401,
+                                };
                                 if (onError)
                                     return onError(error);
-                                return res.status(500).json(error);
-                            }
-                            if (optional) {
-                                req.userId = null;
-                                req.user = null;
-                                return next();
+                                return res.status(401).json(error);
                             }
-                            const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token signature', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+                            logger.error('[oxy.auth] Unexpected error during service token verification', verifyError, {
+                                component: 'auth',
+                                method: 'auth.serviceToken',
+                            });
+                            const error = {
+                                error: 'AUTH_INTERNAL_ERROR',
+                                message: 'Internal authentication error',
+                                code: 'AUTH_INTERNAL_ERROR',
+                                status: 500,
+                            };
                             if (onError)
                                 return onError(error);
-                            return res.status(401).json(error);
+                            return res.status(500).json(error);
                         }
-                        // Check expiration
-                        if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                        // Check expiration — reject tokens at exact expiry second (use <=)
+                        if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -272,7 +419,8 @@ export function OxyServicesUtilityMixin(Base) {
                             return res.status(401).json(error);
                         }
                         // Validate required service token fields
-                        if (!decoded.appId) {
+                        const appId = decoded.appId;
+                        if (!appId) {
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -284,16 +432,52 @@ export function OxyServicesUtilityMixin(Base) {
                             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;
+                        const oxyUserIdRaw = req.headers['x-oxy-user-id'];
+                        const oxyUserId = typeof oxyUserIdRaw === 'string' && oxyUserIdRaw.length > 0 ? oxyUserIdRaw : null;
+                        // C3: a service may only act as a user when an explicit
+                        // ServiceActingAs grant exists for that (appId, userId) pair.
+                        // Without the grant we MUST refuse — silently attaching
+                        // `req.userId = oxyUserId` would let any service impersonate
+                        // any user simply by setting the header.
+                        if (oxyUserId) {
+                            const grant = await oxyInstance.verifyServiceActingAs(appId, oxyUserId);
+                            if (!grant || !grant.authorized) {
+                                logger.warn('[oxy.auth] Service token rejected — no delegation grant', {
+                                    component: 'auth',
+                                    method: 'auth.serviceToken',
+                                    appId,
+                                    attemptedUserId: oxyUserId,
+                                });
+                                const error = {
+                                    error: 'SERVICE_ACTING_AS_UNAUTHORIZED',
+                                    message: 'Service not authorized to act as this user',
+                                    code: 'SERVICE_ACTING_AS_UNAUTHORIZED',
+                                    status: 403,
+                                };
+                                if (onError)
+                                    return onError(error);
+                                return res.status(403).json(error);
+                            }
+                            req.userId = oxyUserId;
+                            req.user = { id: oxyUserId };
+                            req.serviceActingAs = { userId: oxyUserId, scopes: grant.scopes };
+                        }
+                        else {
+                            // No X-Oxy-User-Id means the service is acting as itself.
+                            req.userId = null;
+                            req.user = null;
+                        }
                         req.accessToken = token;
                         req.serviceApp = {
-                            appId: decoded.appId || '',
+                            appId,
                             appName: decoded.appName || 'unknown',
+                            scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
                         };
                         if (debug) {
-                            console.log(`[oxy.auth] Service token OK app=${decoded.appName} delegateUser=${oxyUserId || '(none)'}`);
+                            logger.debug(`[oxy.auth] Service token OK app=${decoded.appName} delegateUser=${oxyUserId || '(none)'}`, {
+                                component: 'auth',
+                                method: 'auth.serviceToken',
+                            });
                         }
                         return next();
                     }
@@ -315,7 +499,8 @@ export function OxyServicesUtilityMixin(Base) {
                         return res.status(401).json(error);
                     }
                     // Check token expiration locally first (fast path)
-                    if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                    // Reject tokens at exact expiry second (use <=)
+                    if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
                         if (optional) {
                             req.userId = null;
                             req.user = null;
@@ -366,7 +551,10 @@ export function OxyServicesUtilityMixin(Base) {
                                 req.user = { id: userId };
                             }
                             if (debug) {
-                                console.log(`[oxy.auth] OK user=${userId} session=${decoded.sessionId}`);
+                                logger.debug(`[oxy.auth] OK user=${userId} session=${decoded.sessionId}`, {
+                                    component: 'auth',
+                                    method: 'auth',
+                                });
                             }
                             // Process X-Acting-As header before proceeding
                             if (await processActingAs())
@@ -375,7 +563,10 @@ export function OxyServicesUtilityMixin(Base) {
                         }
                         catch (validationError) {
                             if (debug) {
-                                console.log(`[oxy.auth] Session validation failed:`, validationError);
+                                logger.debug('[oxy.auth] Session validation failed', {
+                                    component: 'auth',
+                                    method: 'auth',
+                                }, validationError);
                             }
                             if (optional) {
                                 req.userId = null;
@@ -415,25 +606,44 @@ export function OxyServicesUtilityMixin(Base) {
                                 req.user = fullUser;
                             }
                         }
-                        catch {
-                            // Failed to load user, continue with basic user object
+                        catch (loadUserError) {
+                            // Loading the full user is best-effort here; the basic { id }
+                            // object is already attached. Log so misconfigured deployments
+                            // can be diagnosed instead of silently failing.
+                            logger.warn('[oxy.auth] loadUser fallback — could not fetch full profile', {
+                                component: 'auth',
+                                method: 'auth.loadUser',
+                                userId,
+                            }, loadUserError);
                         }
                     }
                     if (debug) {
-                        console.log(`[oxy.auth] OK user=${userId} (no session)`);
+                        logger.debug(`[oxy.auth] OK user=${userId} (no session)`, {
+                            component: 'auth',
+                            method: 'auth',
+                        });
                     }
                     // Process X-Acting-As header before proceeding
                     if (await processActingAs())
                         next();
                 }
                 catch (error) {
-                    const apiError = oxyInstance.handleError(error);
+                    const handled = oxyInstance.handleError(error);
+                    const apiError = {
+                        message: handled.message || 'Authentication error',
+                        code: handled.code ?? 'AUTH_ERROR',
+                        status: handled.status ?? 500,
+                        details: handled.details,
+                    };
                     if (debug) {
-                        console.log(`[oxy.auth] Error:`, apiError);
+                        logger.debug('[oxy.auth] Error', {
+                            component: 'auth',
+                            method: 'auth',
+                        }, apiError);
                     }
                     if (onError)
                         return onError(apiError);
-                    return res.status((apiError && apiError.status) || 500).json(apiError);
+                    return res.status(apiError.status).json(apiError);
                 }
             };
         }
@@ -463,7 +673,7 @@ export function OxyServicesUtilityMixin(Base) {
          */
         authSocket(options = {}) {
             const { debug = false } = options;
-            // Cast to any for cross-mixin method access (Auth mixin methods available at runtime)
+            // Cross-mixin method access typed via the same structural subset.
             const oxyInstance = this;
             return async (socket, next) => {
                 try {
@@ -475,15 +685,21 @@ export function OxyServicesUtilityMixin(Base) {
                     try {
                         decoded = jwtDecode(token);
                     }
-                    catch {
+                    catch (decodeError) {
+                        if (debug) {
+                            logger.debug('[oxy.authSocket] Token decode failed', {
+                                component: 'auth',
+                                method: 'authSocket',
+                            }, decodeError);
+                        }
                         return next(new Error('Invalid token'));
                     }
                     const userId = decoded.userId || decoded.id;
                     if (!userId) {
                         return next(new Error('Invalid token payload'));
                     }
-                    // Check expiration
-                    if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                    // Check expiration — reject tokens at exact expiry second (use <=)
+                    if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
                         return next(new Error('Token expired'));
                     }
                     // Validate session if available
@@ -496,25 +712,39 @@ export function OxyServicesUtilityMixin(Base) {
                                 return next(new Error('Session invalid'));
                             }
                         }
-                        catch {
+                        catch (validateErr) {
+                            if (debug) {
+                                logger.debug('[oxy.authSocket] Session validation failed', {
+                                    component: 'auth',
+                                    method: 'authSocket',
+                                }, validateErr);
+                            }
                             return next(new Error('Session validation failed'));
                         }
                     }
-                    // Attach user data to socket
+                    // Attach user data to socket. We expose BOTH `socket.data.userId`
+                    // (the official Socket.IO data slot) and `socket.user` because
+                    // every consumer in this ecosystem (Mention, Allo, api/server.ts)
+                    // reads from `socket.user.id`.
                     socket.data = socket.data || {};
                     socket.data.userId = userId;
                     socket.data.sessionId = decoded.sessionId || null;
                     socket.data.token = token;
-                    // Also set on socket.user for backward compatibility
                     socket.user = { id: userId, userId, sessionId: decoded.sessionId };
                     if (debug) {
-                        console.log(`[oxy.authSocket] OK user=${userId}`);
+                        logger.debug(`[oxy.authSocket] OK user=${userId}`, {
+                            component: 'auth',
+                            method: 'authSocket',
+                        });
                     }
                     next();
                 }
                 catch (err) {
                     if (debug) {
-                        console.log(`[oxy.authSocket] Error:`, err);
+                        logger.debug('[oxy.authSocket] Error', {
+                            component: 'auth',
+                            method: 'authSocket',
+                        }, err);
                     }
                     next(new Error('Authentication error'));
                 }
@@ -528,7 +758,7 @@ export function OxyServicesUtilityMixin(Base) {
          * @example
          * ```typescript
          * // Protect internal endpoints
-         * app.use('/internal', oxy.serviceAuth());
+         * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
          *
          * app.post('/internal/trigger', (req, res) => {
          *   console.log('Service app:', req.serviceApp);
@@ -551,5 +781,114 @@ export function OxyServicesUtilityMixin(Base) {
                 });
             };
         }
+        /**
+         * Express.js middleware that enforces a specific service-token scope.
+         *
+         * Mount AFTER `auth()` / `serviceAuth()` — relies on `req.serviceApp` and
+         * (when delegation is in effect) `req.serviceActingAs.scopes`. The scope
+         * is granted if EITHER list contains it, mirroring the OAuth2 model where
+         * the app's app-level scopes and the per-user delegated scopes both count.
+         *
+         * Requests authenticated as a regular user (no service token) are rejected
+         * with 403 — scope-protected endpoints are service-to-service by design.
+         *
+         * @example
+         * ```typescript
+         * app.use(
+         *   '/internal/files',
+         *   oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }),
+         *   oxy.requireScope('files:write'),
+         * );
+         * ```
+         */
+        requireScope(scope) {
+            if (typeof scope !== 'string' || scope.length === 0) {
+                throw new Error('requireScope: scope must be a non-empty string');
+            }
+            return (req, res, next) => {
+                const appScopes = req.serviceApp?.scopes ?? [];
+                const delegatedScopes = req.serviceActingAs?.scopes ?? [];
+                if (!req.serviceApp) {
+                    res.status(403).json({
+                        error: 'SERVICE_TOKEN_REQUIRED',
+                        message: 'Scope-protected endpoint requires a service token',
+                        code: 'SERVICE_TOKEN_REQUIRED',
+                        status: 403,
+                    });
+                    return;
+                }
+                if (appScopes.includes(scope) || delegatedScopes.includes(scope)) {
+                    next();
+                    return;
+                }
+                logger.warn('[oxy.auth] Service token missing required scope', {
+                    component: 'auth',
+                    method: 'requireScope',
+                    appId: req.serviceApp.appId,
+                    required: scope,
+                });
+                res.status(403).json({
+                    error: 'INSUFFICIENT_SCOPE',
+                    message: `Required scope '${scope}' not granted`,
+                    code: 'INSUFFICIENT_SCOPE',
+                    status: 403,
+                });
+            };
+        }
     };
 }
+// ---------------------------------------------------------------------------
+// Service token verification helpers
+// ---------------------------------------------------------------------------
+/**
+ * Verify a service JWT's HMAC-SHA256 signature using a constant-time compare.
+ * Throws `ServiceTokenStructureError` on malformed tokens and
+ * `ServiceTokenSignatureError` on signature mismatch — both map to 401.
+ */
+async function verifyServiceTokenSignature(token, secret) {
+    const nodeCrypto = await loadNodeCrypto();
+    const { createHmac, timingSafeEqual } = nodeCrypto;
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        throw new ServiceTokenStructureError(`Service token must have 3 parts, got ${parts.length}`);
+    }
+    const [headerB64, payloadB64, signatureB64] = parts;
+    if (!headerB64 || !payloadB64 || !signatureB64) {
+        throw new ServiceTokenStructureError('Service token has empty segment');
+    }
+    const expectedSig = createHmac('sha256', secret)
+        .update(`${headerB64}.${payloadB64}`)
+        .digest('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+    const sigBuf = Buffer.from(signatureB64);
+    const expectedBuf = Buffer.from(expectedSig);
+    if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
+        throw new ServiceTokenSignatureError();
+    }
+}
+/**
+ * Verify that a decoded service-token payload carries the expected `aud`,
+ * `iss`, and `type` claims. Throws `ServiceTokenClaimError` on mismatch.
+ * This is the defence against the H4 vulnerability where a recovery / 2FA /
+ * access token signed by the same shared secret could be replayed as a
+ * service token because no claim binding existed.
+ */
+function verifyServiceTokenClaims(decoded, expected) {
+    if (decoded.type !== 'service') {
+        throw new ServiceTokenClaimError(`Service token has unexpected type '${String(decoded.type)}'`);
+    }
+    if (decoded.iss !== expected.issuer) {
+        throw new ServiceTokenClaimError(`Service token issuer mismatch: expected '${expected.issuer}', got '${String(decoded.iss)}'`);
+    }
+    const aud = decoded.aud;
+    if (Array.isArray(aud)) {
+        if (!aud.includes(expected.audience)) {
+            throw new ServiceTokenClaimError(`Service token audience does not include '${expected.audience}'`);
+        }
+    }
+    else if (aud !== expected.audience) {
+        throw new ServiceTokenClaimError(`Service token audience mismatch: expected '${expected.audience}', got '${String(aud)}'`);
+    }
+}