@uns-kit/api 3.0.41 → 3.0.42

package/README.md

@@ -14,6 +14,14 @@ For the MQTT topic registry published by the API plugin, see `../../docs/uns-top
 | [`@uns-kit/cron`](https://github.com/uns-openhub/uns-kit/tree/main/packages/uns-cron) | Cron-driven scheduler that emits UNS events on a fixed cadence.             |
 | [`@uns-kit/cli`](https://github.com/uns-openhub/uns-kit/tree/main/packages/uns-cli)   | CLI for scaffolding new UNS applications.                                   |
 
+## Declared operator operations (local source candidate)
+
+See the shared [operator API contract and example](../../docs/operator-api.md).
+An application explicitly declares its read/command operations; the SDK enforces
+current authority and exact launch/body binding. Application business checks and
+durable command receipts remain application-owned. Legacy endpoints gain no
+operator grant automatically.
+
 ## Installation
 
 ```bash

package/dist/app.js

@@ -9,6 +9,7 @@ import { basePath } from "@uns-kit/core/base-path.js";
 import logger from "@uns-kit/core/logger.js";
 import os from 'os';
 import { logRequestContext } from "./request-log.js";
+import { OPERATOR_OUTCOME_HEADER } from "@uns-kit/core/runtime/operator-api.js";
 const normalizeBasePrefix = (value) => {
     if (!value)
         return "";
@@ -93,6 +94,7 @@ export default class App {
                 return next();
             if (!this.ownershipGate()) {
                 res.setHeader("Retry-After", "1");
+                res.setHeader(OPERATOR_OUTCOME_HEADER, "not-applied");
                 res.status(503).json({ error: "RUNTIME_PASSIVE", message: "Runtime ownership is being transferred. Retry the request." });
                 return;
             }

package/dist/operator-api-authority.d.ts

@@ -0,0 +1,26 @@
+import { type OperatorDeployment, type OperatorOperation, type OperatorOperationDefinition } from "@uns-kit/core/runtime/operator-api.js";
+/** Use only when the application can prove its command had no external effect.
+ * A database/transport failure after a possible commit must stay uncertain. */
+export declare function markOperatorNotApplied(response: {
+    setHeader(name: string, value: string): unknown;
+}): void;
+export declare function operatorEndpointDeclarations(definitions: OperatorOperationDefinition[] | undefined, method: string, path: string, authenticationConfigured: boolean): OperatorOperation[];
+/** Route callbacks pass claims only after the existing JWT/JWKS/path checks.
+ * Delegated authority is bound again here, inside the application process. */
+export declare class OperatorApiAuthority {
+    private readonly options;
+    private pending;
+    constructor(options: {
+        deployment: () => OperatorDeployment;
+        statusUrl?: string;
+        fetch?: typeof fetch;
+    });
+    authorize(input: {
+        declarations: OperatorOperation[];
+        claims: Record<string, unknown>;
+        authorization: string;
+        payload: unknown;
+        query?: Record<string, unknown>;
+    }): Promise<OperatorOperation | undefined>;
+    private currentAuthorization;
+}

package/dist/operator-api-authority.js

@@ -0,0 +1,128 @@
+import { OPERATOR_DELEGATION_CLAIM, OPERATOR_OUTCOME_HEADER, OperatorApiError, assertOperatorDelegation, assertOperatorPayload, operatorDeploymentSchema, operatorOperation, } from "@uns-kit/core/runtime/operator-api.js";
+/** Use only when the application can prove its command had no external effect.
+ * A database/transport failure after a possible commit must stay uncertain. */
+export function markOperatorNotApplied(response) {
+    response.setHeader(OPERATOR_OUTCOME_HEADER, "not-applied");
+}
+export function operatorEndpointDeclarations(definitions, method, path, authenticationConfigured) {
+    if (!definitions?.length)
+        return [];
+    if (!authenticationConfigured)
+        throw new OperatorApiError("operator_endpoint_requires_authentication", 503);
+    if (definitions.length > 16)
+        throw new OperatorApiError("operator_endpoint_declaration_limit");
+    const parsed = definitions.map((d) => operatorOperation(d, method, path));
+    if (new Set(parsed.map((d) => d.id)).size !== parsed.length)
+        throw new OperatorApiError("operator_endpoint_duplicate_id");
+    return parsed;
+}
+/** Route callbacks pass claims only after the existing JWT/JWKS/path checks.
+ * Delegated authority is bound again here, inside the application process. */
+export class OperatorApiAuthority {
+    options;
+    pending = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    async authorize(input) {
+        const delegated = input.claims[OPERATOR_DELEGATION_CLAIM] !== undefined;
+        if (!input.declarations.length) {
+            if (delegated)
+                throw new OperatorApiError("operator_endpoint_not_declared", 403);
+            return undefined;
+        }
+        const roles = [input.claims["role"], ...(Array.isArray(input.claims["roles"]) ? input.claims["roles"] : [])];
+        if (!roles.some((r) => r === "admin" || r === "operator") || typeof input.claims["sub"] !== "string" || !input.claims["sub"])
+            throw new OperatorApiError("operator_role_required", 403);
+        if (input.query && Object.keys(input.query).length)
+            throw new OperatorApiError("operator_query_not_supported");
+        const matched = input.declarations.filter((d) => {
+            try {
+                assertOperatorPayload(d, input.payload);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (matched.length !== 1)
+            throw new OperatorApiError(matched.length ? "operator_request_ambiguous" : "operator_request_invalid");
+        const operation = matched[0];
+        if (delegated) {
+            let deployment;
+            try {
+                deployment = operatorDeploymentSchema.parse(this.options.deployment());
+            }
+            catch {
+                throw new OperatorApiError("operator_deployment_unavailable", 503);
+            }
+            try {
+                assertOperatorDelegation(input.claims, operation, input.payload, deployment);
+            }
+            catch {
+                throw new OperatorApiError("operator_delegation_rejected", 403);
+            }
+            if (!this.options.statusUrl)
+                throw new OperatorApiError("operator_authorization_status_required", 503);
+        }
+        // A standalone, locally verified native operator token can remain offline.
+        // Delegated machine authority always requires a fresh parent-status check.
+        if (this.options.statusUrl)
+            await this.currentAuthorization(input.authorization);
+        return operation;
+    }
+    async currentAuthorization(authorization) {
+        if (this.pending >= 4)
+            throw new OperatorApiError("operator_authorization_capacity", 503);
+        this.pending++;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 1000);
+        try {
+            const response = await (this.options.fetch ?? fetch)(this.options.statusUrl, {
+                method: "POST",
+                headers: { authorization },
+                signal: controller.signal,
+                redirect: "error",
+            });
+            if (response.status === 401 || response.status === 403)
+                throw new OperatorApiError("operator_authorization_inactive", 403);
+            if (!response.ok || Number(response.headers.get("content-length") ?? 0) > 4096)
+                throw new OperatorApiError("operator_authorization_unavailable", 503);
+            if (!response.body)
+                throw new OperatorApiError("operator_authorization_unavailable", 503);
+            const reader = response.body.getReader();
+            let length = 0, body = "";
+            try {
+                const decoder = new TextDecoder();
+                while (true) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    length += part.value.byteLength;
+                    if (length > 4096) {
+                        await reader.cancel();
+                        throw new OperatorApiError("operator_authorization_unavailable", 503);
+                    }
+                    body += decoder.decode(part.value, { stream: true });
+                }
+                body += decoder.decode();
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const status = JSON.parse(body);
+            if (status.active !== true || status.protocolVersion !== 1)
+                throw new OperatorApiError("operator_authorization_inactive", 403);
+        }
+        catch (error) {
+            if (error instanceof OperatorApiError)
+                throw error;
+            throw new OperatorApiError("operator_authorization_unavailable", 503);
+        }
+        finally {
+            controller.abort();
+            clearTimeout(timer);
+            this.pending--;
+        }
+    }
+}

package/dist/operator-jwt.d.ts

@@ -0,0 +1,12 @@
+/** Purpose-specific JWKS uses existing approved service public keys. PS256/type/
+ * audience keep these tokens out of the normal RS256 API/GraphQL credential path. */
+export declare class OperatorJwtVerifier {
+    private readonly url?;
+    private readonly fetcher;
+    private keys;
+    private expires;
+    private pending;
+    constructor(url?: string, fetcher?: typeof fetch);
+    verify(token: string): Promise<Record<string, unknown>>;
+    private load;
+}

package/dist/operator-jwt.js

@@ -0,0 +1,89 @@
+import { OPERATOR_JWT_ALGORITHM, OPERATOR_JWT_AUDIENCE, OPERATOR_JWT_TYPE, OperatorApiError } from "@uns-kit/core/runtime/operator-api.js";
+import jwt from "jsonwebtoken";
+import { createPublicKey } from "node:crypto";
+/** Purpose-specific JWKS uses existing approved service public keys. PS256/type/
+ * audience keep these tokens out of the normal RS256 API/GraphQL credential path. */
+export class OperatorJwtVerifier {
+    url;
+    fetcher;
+    keys = [];
+    expires = 0;
+    pending;
+    constructor(url, fetcher = fetch) {
+        this.url = url;
+        this.fetcher = fetcher;
+    }
+    async verify(token) {
+        const decoded = jwt.decode(token, { complete: true });
+        if (!decoded ||
+            decoded.header.alg !== OPERATOR_JWT_ALGORITHM ||
+            decoded.header.typ !== OPERATOR_JWT_TYPE ||
+            typeof decoded.header.kid !== "string" ||
+            decoded.header.kid.length > 256 ||
+            !this.url)
+            throw new OperatorApiError("operator_jwt_invalid", 401);
+        if (Date.now() >= this.expires || !this.keys.some((k) => k["kid"] === decoded.header.kid))
+            await this.load();
+        const keys = this.keys.filter((k) => k["kid"] === decoded.header.kid && k["kty"] === "RSA" && k["alg"] === OPERATOR_JWT_ALGORITHM && !k["d"]);
+        if (keys.length !== 1)
+            throw new OperatorApiError("operator_jwt_key_unavailable", 401);
+        try {
+            const key = createPublicKey({ key: keys[0], format: "jwk" });
+            const claims = jwt.verify(token, key, { algorithms: [OPERATOR_JWT_ALGORITHM], audience: OPERATOR_JWT_AUDIENCE, maxAge: "30s" });
+            if (!claims || typeof claims !== "object")
+                throw new Error("invalid");
+            return claims;
+        }
+        catch {
+            throw new OperatorApiError("operator_jwt_invalid", 401);
+        }
+    }
+    async load() {
+        this.pending ??= (async () => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 1000);
+            try {
+                const response = await this.fetcher(this.url, { redirect: "error", signal: controller.signal });
+                if (!response.ok || !response.body || Number(response.headers.get("content-length") ?? 0) > 131072)
+                    throw new Error("unavailable");
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let size = 0, body = "";
+                try {
+                    while (true) {
+                        const part = await reader.read();
+                        if (part.done)
+                            break;
+                        size += part.value.byteLength;
+                        if (size > 131072) {
+                            await reader.cancel();
+                            throw new Error("oversize");
+                        }
+                        body += decoder.decode(part.value, { stream: true });
+                    }
+                    body += decoder.decode();
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                const document = JSON.parse(body);
+                if (!Array.isArray(document.keys) || document.keys.length > 64)
+                    throw new Error("invalid");
+                this.keys = document.keys;
+                this.expires = Date.now() + 15000;
+            }
+            catch {
+                this.keys = [];
+                this.expires = 0;
+                throw new OperatorApiError("operator_jwks_unavailable", 503);
+            }
+            finally {
+                controller.abort();
+                clearTimeout(timer);
+            }
+        })().finally(() => {
+            this.pending = undefined;
+        });
+        return this.pending;
+    }
+}

package/dist/service-api-request-body.d.ts

@@ -0,0 +1,6 @@
+import type { IPostEndpointOptions } from "@uns-kit/core/uns/uns-interfaces.js";
+/** Service APIs and OpenAPI must agree when a caller overrides requestBody on
+ * api.post/put/patch/delete after buildServiceApiInteractions(). A body editor
+ * needs the body descriptor even when no flattened catalog schema was supplied.
+ * The full JSON Schema stays authoritative in the existing OpenAPI document. */
+export declare function withServiceApiRequestBody(serviceApi: Record<string, unknown> | null | undefined, requestBody: IPostEndpointOptions["requestBody"]): Record<string, unknown> | null;

package/dist/service-api-request-body.js

@@ -0,0 +1,20 @@
+/** Service APIs and OpenAPI must agree when a caller overrides requestBody on
+ * api.post/put/patch/delete after buildServiceApiInteractions(). A body editor
+ * needs the body descriptor even when no flattened catalog schema was supplied.
+ * The full JSON Schema stays authoritative in the existing OpenAPI document. */
+export function withServiceApiRequestBody(serviceApi, requestBody) {
+    if (!serviceApi || !requestBody)
+        return serviceApi ?? null;
+    const raw = serviceApi["requestBody"];
+    const previous = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    return {
+        ...serviceApi,
+        requestBody: {
+            ...previous,
+            required: requestBody.required ?? true,
+            description: requestBody.description ?? previous["description"] ?? null,
+            contentType: "application/json",
+            schemas: Array.isArray(previous["schemas"]) ? previous["schemas"] : [],
+        },
+    };
+}

package/dist/uns-api-proxy.d.ts

@@ -21,12 +21,15 @@ export default class UnsApiProxy extends UnsProxy {
     private statusInterval;
     private readonly statusIntervalMs;
     private readonly dataCatalogOffers;
+    private readonly operatorAuthority;
+    private readonly operatorJwt;
     constructor(processName: string, instanceName: string, options: IApiProxyOptions);
     setOwnershipGate(gate: () => boolean): void;
     drainRequests(): Promise<void>;
     /** Track an explicitly read-only handler through completion, including client disconnects. */
     runReadOnlyRequest<T>(res: Response, operation: () => T | Promise<T>): Promise<T>;
     getProcessName(): string;
+    private operatorAuthorized;
     private getPublishedApiHost;
     /**
      * Unregister endpoint
@@ -69,6 +72,7 @@ export default class UnsApiProxy extends UnsProxy {
     private emitStatusMetrics;
     private registerHealthEndpoint;
     private getApiEventName;
+    private verifyRequestToken;
     private extractBearerToken;
     private getPublicKeyFromJwks;
     private fetchJwksKeys;

package/dist/uns-api-proxy.js

@@ -1,3 +1,4 @@
+import { withServiceApiRequestBody } from "./service-api-request-body.js";
 import { readFileSync } from "fs";
 import jwt from "jsonwebtoken";
 import * as path from "path";
@@ -12,6 +13,9 @@ import { UnsTopicMatcher } from "@uns-kit/core/uns/uns-topic-matcher.js";
 import { DataSizeMeasurements, PhysicalMeasurements } from "@uns-kit/core/uns/uns-measurements.js";
 import { buildUnsRoutePath } from "@uns-kit/core/uns/uns-path.js";
 import App from "./app.js";
+import { OperatorApiAuthority, operatorEndpointDeclarations, markOperatorNotApplied } from "./operator-api-authority.js";
+import { OPERATOR_API_EXTENSION, OPERATOR_AUTH_SCHEME, OPERATOR_DELEGATION_CLAIM, OperatorApiError } from "@uns-kit/core/runtime/operator-api.js";
+import { OperatorJwtVerifier } from "./operator-jwt.js";
 const packageJsonPath = path.join(basePath, "package.json");
 const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 const normalizeBasePrefix = (value) => {
@@ -61,9 +65,18 @@ export default class UnsApiProxy extends UnsProxy {
     statusInterval = null;
     statusIntervalMs = 10_000;
     dataCatalogOffers = new Map();
+    operatorAuthority;
+    operatorJwt;
     constructor(processName, instanceName, options) {
         super();
         this.options = options;
+        const controllerBase = process.env.UNS_CONTROLLER_PUBLIC_BASE;
+        const statusUrl = options.operatorAuthorizationStatusUrl ?? (controllerBase ? new URL("/api/auth/token-status", controllerBase).href : undefined);
+        this.operatorJwt = new OperatorJwtVerifier(options.operatorJwksUrl ?? (controllerBase ? new URL("/api/auth/operator-jwks.json", controllerBase).href : undefined));
+        this.operatorAuthority = new OperatorApiAuthority({ ...(statusUrl ? { statusUrl } : {}), deployment: () => ({
+                controllerName: process.env.UNS_ROUTE_CONTROLLER_NAME, rttNode: process.env.RTT_NODE,
+                version: process.env.version ?? packageJson.version, instanceId: process.env.RTT_INSTANCE_ID, launchId: process.env.UNS_ROUTE_LAUNCH_ID,
+            }) });
         this.apiBasePrefix =
             normalizeBasePrefix(options.apiBasePath ?? process.env.UNS_API_BASE_PATH) || "/api";
         const rawSwaggerBase = normalizeBasePrefix(options.swaggerBasePath ?? process.env.UNS_SWAGGER_BASE_PATH) || this.apiBasePrefix;
@@ -101,6 +114,25 @@ export default class UnsApiProxy extends UnsProxy {
     getProcessName() {
         return this.processName;
     }
+    async operatorAuthorized(req, res, decoded, declarations) {
+        try {
+            const delegatedScheme = String(req.headers.authorization ?? "").startsWith(OPERATOR_AUTH_SCHEME + " ");
+            if (delegatedScheme !== (decoded[OPERATOR_DELEGATION_CLAIM] !== undefined))
+                throw new OperatorApiError("operator_jwt_purpose_mismatch", 403);
+            const normalizedAuthorization = delegatedScheme ? "Bearer " + req.headers.authorization.slice(OPERATOR_AUTH_SCHEME.length + 1) : req.headers.authorization;
+            await this.operatorAuthority.authorize({ claims: decoded, declarations, payload: req.method === "GET" ? {} : req.body,
+                authorization: normalizedAuthorization, query: req.query });
+            // Existing application handlers inspect an already-verified bearer.
+            req.headers.authorization = normalizedAuthorization;
+            return true;
+        }
+        catch (error) {
+            const status = error instanceof OperatorApiError ? error.status : 503;
+            markOperatorNotApplied(res);
+            res.status(status).json({ error: error instanceof OperatorApiError ? error.code : "operator_authorization_unavailable" });
+            return false;
+        }
+    }
     getPublishedApiHost() {
         const addressInfo = this.app.server.address();
         const port = addressInfo && typeof addressInfo === "object" ? addressInfo.port : undefined;
@@ -166,6 +198,7 @@ export default class UnsApiProxy extends UnsProxy {
         const fullPath = buildUnsRoutePath(topic, asset, objectType, objectId, attribute);
         const apiPath = `${this.apiBasePrefix}${fullPath}`.replace(/\/{2,}/g, "/");
         const swaggerPath = buildSwaggerPath(this.swaggerBasePrefix, this.processName, this.instanceName);
+        const operatorDeclarations = operatorEndpointDeclarations(options?.operatorOperations, "GET", fullPath, Boolean(this.options.jwks?.wellKnownJwksUrl || this.options.jwtSecret));
         try {
             this.registerApiEndpoint({
                 timestamp: time,
@@ -222,9 +255,7 @@ export default class UnsApiProxy extends UnsProxy {
                         const token = this.extractBearerToken(req, res);
                         if (!token)
                             return; // response already sent
-                        const publicKey = await this.getPublicKeyFromJwks(token);
-                        const algorithms = this.options.jwks.algorithms || ["RS256"];
-                        const decoded = jwt.verify(token, publicKey, { algorithms });
+                        const decoded = await this.verifyRequestToken(req, token);
                         const accessRules = Array.isArray(decoded?.accessRules)
                             ? decoded.accessRules
                             : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
@@ -236,22 +267,26 @@ export default class UnsApiProxy extends UnsProxy {
                         if (!allowed) {
                             return res.status(403).json({ error: "Path not allowed by token access rules" });
                         }
+                        if (!await this.operatorAuthorized(req, res, decoded, operatorDeclarations))
+                            return;
                         handler(req, res);
                     }
                     catch (err) {
+                        if (err instanceof OperatorApiError) {
+                            markOperatorNotApplied(res);
+                            return res.status(err.status).json({ error: err.code });
+                        }
                         return res.status(401).json({ error: "Invalid token" });
                     }
                 });
             }
             else if (this.options?.jwtSecret) {
-                this.app.router.get(fullPath, (req, res) => {
-                    const authHeader = req.headers["authorization"];
-                    if (!authHeader || !authHeader.startsWith("Bearer ")) {
-                        return res.status(401).json({ error: "Missing or invalid Authorization header" });
-                    }
-                    const token = authHeader.slice(7);
+                this.app.router.get(fullPath, async (req, res) => {
+                    const token = this.extractBearerToken(req, res);
+                    if (!token)
+                        return;
                     try {
-                        const decoded = jwt.verify(token, process.env.JWT_SECRET || this.options.jwtSecret);
+                        const decoded = await this.verifyRequestToken(req, token);
                         const accessRules = Array.isArray(decoded?.accessRules)
                             ? decoded.accessRules
                             : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
@@ -263,9 +298,15 @@ export default class UnsApiProxy extends UnsProxy {
                         if (!allowed) {
                             return res.status(403).json({ error: "Path not allowed by token access rules" });
                         }
+                        if (!await this.operatorAuthorized(req, res, decoded, operatorDeclarations))
+                            return;
                         handler(req, res);
                     }
                     catch (err) {
+                        if (err instanceof OperatorApiError) {
+                            markOperatorNotApplied(res);
+                            return res.status(err.status).json({ error: err.code });
+                        }
                         return res.status(401).json({ error: "Invalid token" });
                     }
                 });
@@ -325,6 +366,9 @@ export default class UnsApiProxy extends UnsProxy {
                     },
                 };
             }
+            if (operatorDeclarations.length && this.app.swaggerSpec?.paths?.[apiPath]?.get) {
+                this.app.swaggerSpec.paths[apiPath].get[OPERATOR_API_EXTENSION] = operatorDeclarations;
+            }
         }
         catch (error) {
             logger.error(`${this.instanceNameWithSuffix} - Error publishing message to route ${fullPath}: ${error.message}`);
@@ -430,6 +474,7 @@ export default class UnsApiProxy extends UnsProxy {
         const apiPath = `${this.apiBasePrefix}${fullPath}`.replace(/\/{2,}/g, "/");
         const swaggerPath = buildSwaggerPath(this.swaggerBasePrefix, this.processName, this.instanceName);
         const methodKey = method.toLowerCase();
+        const operatorDeclarations = operatorEndpointDeclarations(options?.operatorOperations, method, fullPath, Boolean(this.options.jwks?.wellKnownJwksUrl || this.options.jwtSecret));
         try {
             this.registerApiEndpoint({
                 timestamp: time,
@@ -443,7 +488,7 @@ export default class UnsApiProxy extends UnsProxy {
                 apiMethod: method,
                 apiQueryParams: [],
                 apiDescription: options?.apiDescription,
-                serviceApi: options?.serviceApi ?? null,
+                serviceApi: withServiceApiRequestBody(options?.serviceApi, options?.requestBody),
                 attributeType: UnsAttributeType.Api,
                 apiSwaggerEndpoint: swaggerPath,
                 asset,
@@ -460,9 +505,7 @@ export default class UnsApiProxy extends UnsProxy {
                         const token = this.extractBearerToken(req, res);
                         if (!token)
                             return;
-                        const publicKey = await this.getPublicKeyFromJwks(token);
-                        const algorithms = this.options.jwks.algorithms || ["RS256"];
-                        const decoded = jwt.verify(token, publicKey, { algorithms });
+                        const decoded = await this.verifyRequestToken(req, token);
                         const accessRules = Array.isArray(decoded?.accessRules)
                             ? decoded.accessRules
                             : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
@@ -474,22 +517,26 @@ export default class UnsApiProxy extends UnsProxy {
                         if (!allowed) {
                             return res.status(403).json({ error: "Path not allowed by token access rules" });
                         }
+                        if (!await this.operatorAuthorized(req, res, decoded, operatorDeclarations))
+                            return;
                         handler(req, res);
                     }
                     catch (_err) {
+                        if (_err instanceof OperatorApiError) {
+                            markOperatorNotApplied(res);
+                            return res.status(_err.status).json({ error: _err.code });
+                        }
                         return res.status(401).json({ error: "Invalid token" });
                     }
                 });
             }
             else if (this.options?.jwtSecret) {
-                routerMethod(fullPath, (req, res) => {
-                    const authHeader = req.headers["authorization"];
-                    if (!authHeader || !authHeader.startsWith("Bearer ")) {
-                        return res.status(401).json({ error: "Missing or invalid Authorization header" });
-                    }
-                    const token = authHeader.slice(7);
+                routerMethod(fullPath, async (req, res) => {
+                    const token = this.extractBearerToken(req, res);
+                    if (!token)
+                        return;
                     try {
-                        const decoded = jwt.verify(token, process.env.JWT_SECRET || this.options.jwtSecret);
+                        const decoded = await this.verifyRequestToken(req, token);
                         const accessRules = Array.isArray(decoded?.accessRules)
                             ? decoded.accessRules
                             : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
@@ -501,9 +548,15 @@ export default class UnsApiProxy extends UnsProxy {
                         if (!allowed) {
                             return res.status(403).json({ error: "Path not allowed by token access rules" });
                         }
+                        if (!await this.operatorAuthorized(req, res, decoded, operatorDeclarations))
+                            return;
                         handler(req, res);
                     }
                     catch (_err) {
+                        if (_err instanceof OperatorApiError) {
+                            markOperatorNotApplied(res);
+                            return res.status(_err.status).json({ error: _err.code });
+                        }
                         return res.status(401).json({ error: "Invalid token" });
                     }
                 });
@@ -539,6 +592,9 @@ export default class UnsApiProxy extends UnsProxy {
                     },
                 };
             }
+            if (operatorDeclarations.length && this.app.swaggerSpec?.paths?.[apiPath]?.[methodKey]) {
+                this.app.swaggerSpec.paths[apiPath][methodKey][OPERATOR_API_EXTENSION] = operatorDeclarations;
+            }
         }
         catch (error) {
             logger.error(`${this.instanceNameWithSuffix} - Error registering ${method} route ${fullPath}: ${error.message}`);
@@ -664,13 +720,22 @@ export default class UnsApiProxy extends UnsProxy {
                 return "apiDeleteEvent";
         }
     }
+    async verifyRequestToken(req, token) {
+        if (String(req.headers.authorization ?? "").startsWith(OPERATOR_AUTH_SCHEME + " "))
+            return this.operatorJwt.verify(token);
+        if (this.options.jwks?.wellKnownJwksUrl) {
+            const key = await this.getPublicKeyFromJwks(token);
+            return jwt.verify(token, key, { algorithms: this.options.jwks.algorithms || ["RS256"] });
+        }
+        return jwt.verify(token, process.env.JWT_SECRET || this.options.jwtSecret);
+    }
     extractBearerToken(req, res) {
         const authHeader = req.headers["authorization"];
-        if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        if (typeof authHeader !== "string" || !(authHeader.startsWith("Bearer ") || authHeader.startsWith(OPERATOR_AUTH_SCHEME + " "))) {
             res.status(401).json({ error: "Missing or invalid Authorization header" });
             return undefined;
         }
-        return authHeader.slice(7);
+        return authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader.slice(OPERATOR_AUTH_SCHEME.length + 1);
     }
     async getPublicKeyFromJwks(token) {
         // Decode header to get kid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/api",
-  "version": "3.0.41",
+  "version": "3.0.42",
   "description": "Express-powered API gateway plugin for UnsProxyProcess with JWT/JWKS support.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "multer": "^2.2.0",
     "hyparquet-writer": "^0.16.5",
     "uuid": "^14.0.1",
-    "@uns-kit/core": "3.0.41"
+    "@uns-kit/core": "3.0.42"
   },
   "devDependencies": {
     "@types/cookie-parser": "^1.4.10",