@uns-kit/api 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Aljoša Vister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @uns-kit/api
+
+`@uns-kit/api` exposes Express-based HTTP endpoints for UNS deployments. The plugin attaches a `createApiProxy` method to `UnsProxyProcess`, handles JWT/JWKS access control, and automatically publishes API metadata back into the Unified Namespace.
+
+## Installation
+
+```bash
+pnpm add @uns-kit/api
+# or
+npm install @uns-kit/api
+```
+
+Make sure `@uns-kit/core` is also installed; the plugin augments its runtime types.
+
+## Example
+
+```ts
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import unsApiPlugin, { type UnsProxyProcessWithApi } from "@uns-kit/api";
+
+const process = new UnsProxyProcess("mqtt-broker:1883", { processName: "api-gateway" }) as UnsProxyProcessWithApi;
+unsApiPlugin;
+
+const api = await process.createApiProxy("gateway", { jwtSecret: "super-secret" });
+await api.get("factory/", "status", {
+  apiDescription: "Factory status endpoint",
+  tags: ["status"],
+});
+```
+
+## Scripts
+
+```bash
+pnpm run typecheck
+pnpm run build
+```
+
+`build` emits both JavaScript and type declarations to `dist/`.
+
+## License
+
+MIT © Aljoša Vister

package/dist/api-example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api-example.js

@@ -0,0 +1,54 @@
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import unsApiPlugin from "./uns-api-plugin";
+import { ConfigFile } from "@uns-kit/core/config-file";
+/**
+ * Load the configuration from a file.
+ * On the server, this file is provided by the `uns-datahub-controller`.
+ * In the development environment, you are responsible for creating and maintaining this file and its contents.
+ */
+const config = await ConfigFile.loadConfig();
+/**
+ * Connect to the API proxy process
+ */
+const unsProxyProcess = new UnsProxyProcess(config.infra.host, { processName: config.uns.processName });
+unsApiPlugin;
+const apiOptions = config.uns?.jwksWellKnownUrl
+    ? {
+        jwks: {
+            wellKnownJwksUrl: config.uns.jwksWellKnownUrl,
+            activeKidUrl: config.uns.kidWellKnownUrl,
+        },
+    }
+    : {
+        jwtSecret: "CHANGEME",
+    };
+const apiInput = await unsProxyProcess.createApiProxy("templateUnsApiInput", apiOptions);
+/**
+ * Register an API endpoint and event handler
+ */
+apiInput.get("sij/", "summary-1", {
+    tags: ["Tag1"],
+    apiDescription: "Test API endpoint 1",
+    queryParams: [
+        { name: "filter", type: "string", required: true, description: "Filter za podatke" },
+        { name: "limit", type: "number", required: false, description: "Koliko podatkov želiš" },
+    ]
+});
+apiInput.get("sij/", "summary-2", {
+    tags: ["Tag2"],
+    apiDescription: "Test API endpoint 2",
+    queryParams: [
+        { name: "filter", type: "string", required: true, description: "Filter za podatke" },
+        { name: "limit", type: "number", required: false, description: "Koliko podatkov želiš" },
+    ]
+});
+apiInput.event.on("apiGetEvent", (event) => {
+    try {
+        const appContext = event.req.appContext;
+        // Add SQL query or any other code here
+        event.res.send("OK");
+    }
+    catch (error) {
+        event.res.status(400).send("Error");
+    }
+});

package/dist/api-interfaces.d.ts

@@ -0,0 +1 @@
+export type { IApiProxyOptions, IGetEndpointOptions, QueryParamDef } from "@uns-kit/core/uns/uns-interfaces";

package/dist/api-interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/app.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Module dependencies.
+ */
+import { type Router } from "express";
+import * as http from "http";
+export default class App {
+    private expressApplication;
+    server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    private port;
+    router: Router;
+    private processName;
+    private instanceName;
+    swaggerSpec: {
+        openapi: string;
+        info: {
+            title: string;
+            version: string;
+        };
+        paths: Record<string, any>;
+    };
+    constructor(port: number, processName: string, instanceName: string, appContext?: any);
+    static getExternalIPv4(): string | null;
+    getSwaggerSpec(): {
+        openapi: string;
+        info: {
+            title: string;
+            version: string;
+        };
+        paths: Record<string, any>;
+    };
+    start(): Promise<void>;
+}

package/dist/app.js

@@ -0,0 +1,113 @@
+/**
+ * Module dependencies.
+ */
+import express from "express";
+import * as http from "http";
+import * as path from "path";
+import cookieParser from "cookie-parser";
+import { basePath } from "@uns-kit/core/base-path";
+import logger from "@uns-kit/core/logger";
+import os from 'os';
+export default class App {
+    expressApplication;
+    server;
+    port;
+    router;
+    processName;
+    instanceName;
+    swaggerSpec;
+    constructor(port, processName, instanceName, appContext) {
+        this.router = express.Router();
+        this.port = port;
+        this.expressApplication = express();
+        this.server = http.createServer(this.expressApplication);
+        this.processName = processName;
+        this.instanceName = instanceName;
+        // Add context
+        this.expressApplication.use((req, _res, next) => {
+            req.appContext = appContext;
+            next();
+        });
+        // Body parser (req.body)
+        this.expressApplication.use(express.json());
+        this.expressApplication.use(express.urlencoded({ extended: false }));
+        // Add cookie parser
+        this.expressApplication.use(cookieParser());
+        // Static / public folder
+        const publicHome = process.env.PUBLIC_HOME === null || process.env.PUBLIC_HOME === undefined
+            ? "public"
+            : process.env.PUBLIC_HOME;
+        this.expressApplication.use(express.static(path.join(basePath, publicHome)));
+        // Map routes
+        this.router.use((_req, _res, next) => {
+            logger.info("Time: ", Date.now());
+            next();
+        });
+        this.expressApplication.use("/api", this.router);
+        // Swagger specs
+        this.swaggerSpec = {
+            openapi: "3.0.0",
+            info: {
+                title: "UNS API",
+                version: "1.0.0",
+            },
+            paths: {},
+        };
+    }
+    static getExternalIPv4() {
+        const interfaces = os.networkInterfaces();
+        for (const name of Object.keys(interfaces)) {
+            for (const iface of interfaces[name] || []) {
+                if (iface.family === 'IPv4' && !iface.internal) {
+                    return iface.address;
+                }
+            }
+        }
+        return null;
+    }
+    getSwaggerSpec() {
+        return this.swaggerSpec;
+    }
+    async start() {
+        // Listen on provided port, on all network interfaces.
+        this.server.listen(this.port);
+        this.server.on("error", (error) => {
+            if (error.syscall !== "listen") {
+                throw error;
+            }
+            const bind = typeof this.port === "string"
+                ? `Pipe ${this.port}`
+                : `Port ${this.port}`;
+            // handle specific listen errors with friendly messages
+            switch (error.code) {
+                case "EACCES":
+                    logger.error(`${bind} requires elevated privileges`);
+                    process.exit(1);
+                    break;
+                case "EADDRINUSE":
+                    logger.error(`${bind} is already in use`);
+                    process.exit(1);
+                    break;
+                default:
+                    throw error;
+            }
+        });
+        this.server.on("listening", () => {
+            App.bind(this);
+            const addressInfo = this.server.address();
+            let ip;
+            let port;
+            if (addressInfo && typeof addressInfo === "object") {
+                ip = App.getExternalIPv4();
+                port = addressInfo.port;
+            }
+            else if (typeof addressInfo === "string") {
+                ip = App.getExternalIPv4();
+                port = "";
+            }
+            logger.info(`API listening on http://${ip}:${port}/api`);
+            logger.info(`Swagger openAPI on http://${ip}:${port}/${this.processName}/${this.instanceName}/swagger.json`);
+            this.expressApplication.get(`/${this.processName}/${this.instanceName}/swagger.json`, (req, res) => res.json(this.getSwaggerSpec()));
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from "./uns-api-plugin.js";
+export { UnsApiProxy, type UnsProxyProcessWithApi } from "./uns-api-plugin.js";
+export * from "./api-interfaces.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default } from "./uns-api-plugin.js";
+export { UnsApiProxy } from "./uns-api-plugin.js";
+export * from "./api-interfaces.js";

package/dist/routes/api.d.ts

@@ -0,0 +1,6 @@
+import { type Router } from "express";
+export default class Api {
+    router: Router;
+    private upload;
+    constructor();
+}

package/dist/routes/api.js

@@ -0,0 +1,48 @@
+import express from "express";
+import multer from "multer";
+import logger from "@uns-kit/core/logger";
+export default class Api {
+    router;
+    upload;
+    constructor() {
+        const storage = multer.diskStorage({
+            destination: function (req, file, cb) {
+                cb(null, "tmp/");
+            },
+            filename: function (req, file, cb) {
+                const uniqueSuffix = Date.now() + "-" + Math.round(Math.random() * 1e9);
+                cb(null, file.fieldname + "-" + uniqueSuffix + ".jpg");
+            },
+        });
+        this.upload = multer({ storage: storage });
+        this.router = express.Router();
+        this.router.use((req, res, next) => {
+            logger.info("Time: ", Date.now());
+            next();
+        });
+        /**
+         * Open for all
+         *
+         * Example post request
+         */
+        this.router.post("/call", async function (req, res) {
+            try {
+                const appContext = req.appContext;
+                res.send("OK");
+            }
+            catch (error) {
+                res.status(400).send("Error");
+            }
+        });
+        /**
+         * Open for all
+         *
+         * Upload files
+         */
+        this.router.post("/upload", this.upload.single("file"), function (req, res) {
+            const appContext = req.appContext;
+            logger.info(req.file);
+            res.send("Successfully uploaded files");
+        });
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { IApiProxyOptions } from "@uns-kit/core/uns/uns-interfaces";
+import UnsProxyProcess, { type UnsProxyProcessPlugin } from "@uns-kit/core/uns/uns-proxy-process";
+import UnsApiProxy from "./uns-api-proxy.js";
+declare const unsApiPlugin: UnsProxyProcessPlugin;
+export default unsApiPlugin;
+export { UnsApiProxy };
+export type UnsProxyProcessWithApi = UnsProxyProcess & {
+    createApiProxy(instanceName: string, options: IApiProxyOptions): Promise<UnsApiProxy>;
+};

package/dist/uns-api-plugin.js

@@ -0,0 +1,38 @@
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import UnsApiProxy from "./uns-api-proxy.js";
+const apiProxyRegistry = new WeakMap();
+const getApiProxies = (instance) => {
+    let proxies = apiProxyRegistry.get(instance);
+    if (!proxies) {
+        proxies = [];
+        apiProxyRegistry.set(instance, proxies);
+    }
+    return proxies;
+};
+const unsApiPlugin = ({ define }) => {
+    define({
+        async createApiProxy(instanceName, options) {
+            await this.waitForProcessConnection();
+            const internals = this;
+            const unsApiProxy = new UnsApiProxy(internals.processName, instanceName, options);
+            unsApiProxy.event.on("unsProxyProducedTopics", (event) => {
+                internals.processMqttProxy.publish(event.statusTopic, JSON.stringify(event.producedTopics), {
+                    retain: true,
+                    properties: { messageExpiryInterval: 120000 },
+                });
+            });
+            unsApiProxy.event.on("unsProxyProducedApiEndpoints", (event) => {
+                internals.processMqttProxy.publish(event.statusTopic, JSON.stringify(event.producedApiEndpoints), {
+                    retain: true,
+                    properties: { messageExpiryInterval: 120000 },
+                });
+            });
+            internals.unsApiProxies.push(unsApiProxy);
+            getApiProxies(this).push(unsApiProxy);
+            return unsApiProxy;
+        },
+    });
+};
+UnsProxyProcess.use(unsApiPlugin);
+export default unsApiPlugin;
+export { UnsApiProxy };

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

@@ -0,0 +1,34 @@
+import { UnsAttribute } from "@uns-kit/core/uns/uns-interfaces";
+import UnsProxy from "@uns-kit/core/uns/uns-proxy";
+import { UnsTopics } from "@uns-kit/core/uns/uns-topics";
+import { IApiProxyOptions, IGetEndpointOptions } from "@uns-kit/core/uns/uns-interfaces";
+export default class UnsApiProxy extends UnsProxy {
+    instanceName: string;
+    private topicBuilder;
+    private processName;
+    protected processStatusTopic: string;
+    private app;
+    private options;
+    private jwksCache?;
+    constructor(processName: string, instanceName: string, options: IApiProxyOptions);
+    /**
+     * Unregister endpoint
+     * @param topic - The API topic
+     * @param attribute - The attribute for the topic.
+     * @param method - The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").
+     */
+    unregister(topic: UnsTopics, attribute: UnsAttribute, method: "GET" | "POST" | "PUT" | "DELETE"): Promise<void>;
+    /**
+     * Register a GET endpoint with optional JWT path filter.
+     * @param topic - The API topic
+     * @param attribute - The attribute for the topic.
+     * @param options.description - Optional description.
+     * @param options.tags - Optional tags.
+     */
+    get(topic: UnsTopics, attribute: UnsAttribute, options?: IGetEndpointOptions): Promise<void>;
+    post(..._args: any[]): any;
+    private extractBearerToken;
+    private getPublicKeyFromJwks;
+    private fetchJwksKeys;
+    private certFromX5c;
+}

package/dist/uns-api-proxy.js

@@ -0,0 +1,290 @@
+import { readFileSync } from "fs";
+import jwt from "jsonwebtoken";
+import * as path from "path";
+import { createPublicKey } from "crypto";
+import { basePath } from "@uns-kit/core/base-path";
+import { UnsAttributeType } from "@uns-kit/core/graphql/schema";
+import logger from "@uns-kit/core/logger";
+import { MqttTopicBuilder } from "@uns-kit/core/uns-mqtt/mqtt-topic-builder";
+import { UnsPacket } from "@uns-kit/core/uns/uns-packet";
+import UnsProxy from "@uns-kit/core/uns/uns-proxy";
+import { UnsTopicMatcher } from "@uns-kit/core/uns/uns-topic-matcher";
+import App from "./app.js";
+const packageJsonPath = path.join(basePath, "package.json");
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+export default class UnsApiProxy extends UnsProxy {
+    instanceName;
+    topicBuilder;
+    processName;
+    processStatusTopic;
+    app;
+    options;
+    jwksCache;
+    constructor(processName, instanceName, options) {
+        super();
+        this.options = options;
+        this.app = new App(0, processName, instanceName);
+        this.app.start();
+        this.instanceName = instanceName;
+        this.processName = processName;
+        // Create the topic builder using packageJson values and the processName.
+        this.topicBuilder = new MqttTopicBuilder(`uns-infra/${packageJson.name}/${packageJson.version}/${processName}/`);
+        // Generate the processStatusTopic using the builder.
+        this.processStatusTopic = this.topicBuilder.getProcessStatusTopic();
+        // Derive the instanceStatusTopic by appending the instance name.
+        this.instanceStatusTopic = this.processStatusTopic + instanceName + "/";
+        // Concatenate processName with instanceName for the worker identification.
+        this.instanceNameWithSuffix = `${processName}-${instanceName}`;
+    }
+    /**
+     * Unregister endpoint
+     * @param topic - The API topic
+     * @param attribute - The attribute for the topic.
+     * @param method - The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").
+     */
+    async unregister(topic, attribute, method) {
+        const fullPath = `/${topic}${attribute}`;
+        const apiPath = `/api${fullPath}`;
+        const methodKey = method.toLowerCase(); // Express stores method keys in lowercase
+        // Remove route from router
+        if (this.app.router?.stack) {
+            this.app.router.stack = this.app.router.stack.filter((layer) => {
+                return !(layer.route &&
+                    layer.route.path === fullPath &&
+                    layer.route.methods[methodKey]);
+            });
+        }
+        // Remove from Swagger spec if path exists
+        if (this.app.swaggerSpec?.paths?.[apiPath]) {
+            delete this.app.swaggerSpec.paths[apiPath][methodKey];
+            // If no methods remain for the path, delete the whole path
+            if (Object.keys(this.app.swaggerSpec.paths[apiPath]).length === 0) {
+                delete this.app.swaggerSpec.paths[apiPath];
+            }
+        }
+        // Unregister from internal endpoint tracking
+        this.unregisterApiEndpoint(topic, attribute);
+    }
+    /**
+     * Register a GET endpoint with optional JWT path filter.
+     * @param topic - The API topic
+     * @param attribute - The attribute for the topic.
+     * @param options.description - Optional description.
+     * @param options.tags - Optional tags.
+     */
+    async get(topic, attribute, options) {
+        // Wait until the API server is started
+        while (this.app.server.listening === false) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        const time = UnsPacket.formatToISO8601(new Date());
+        try {
+            // Get ip and port from environment variables or defaults
+            const addressInfo = this.app.server.address();
+            let ip;
+            let port;
+            if (addressInfo && typeof addressInfo === "object") {
+                ip = App.getExternalIPv4();
+                port = addressInfo.port;
+            }
+            else if (typeof addressInfo === "string") {
+                ip = App.getExternalIPv4();
+                port = "";
+            }
+            this.registerApiEndpoint({
+                timestamp: time,
+                topic: topic,
+                attribute: attribute,
+                apiHost: `http://${ip}:${port}`,
+                apiEndpoint: `/api/${topic}${attribute}`,
+                apiMethod: "GET",
+                apiQueryParams: options.queryParams,
+                apiDescription: options?.apiDescription,
+                attributeType: UnsAttributeType.Api,
+                apiSwaggerEndpoint: `/${this.processName}/${this.instanceName}/swagger.json`,
+            });
+            const fullPath = `/${topic}${attribute}`;
+            const handler = (req, res) => {
+                // Query param validation
+                if (options?.queryParams) {
+                    const missingParams = options.queryParams.filter((p) => p.required && req.query[p.name] === undefined).map((p) => p.name);
+                    if (missingParams.length > 0) {
+                        return res.status(400).json({ error: `Missing query params: ${missingParams.join(", ")}` });
+                    }
+                    // Optional: cast types (basic)
+                    for (const param of options.queryParams) {
+                        const value = req.query[param.name];
+                        if (value !== undefined) {
+                            switch (param.type) {
+                                case "number":
+                                    if (isNaN(Number(value))) {
+                                        return res.status(400).json({ error: `Query param ${param.name} must be a number` });
+                                    }
+                                    break;
+                                case "boolean":
+                                    if (!["true", "false", "1", "0"].includes(String(value))) {
+                                        return res.status(400).json({ error: `Query param ${param.name} must be boolean` });
+                                    }
+                                    break;
+                                // string: no check
+                            }
+                        }
+                    }
+                }
+                this.event.emit("apiGetEvent", { req, res });
+            };
+            // JWT or JWKS or open
+            if (this.options?.jwks?.wellKnownJwksUrl) {
+                this.app.router.get(fullPath, async (req, res) => {
+                    try {
+                        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 accessRules = Array.isArray(decoded?.accessRules)
+                            ? decoded.accessRules
+                            : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
+                                ? [decoded.pathFilter]
+                                : undefined);
+                        const allowed = Array.isArray(accessRules)
+                            ? accessRules.some((rule) => UnsTopicMatcher.matches(rule, fullPath))
+                            : false;
+                        if (!allowed) {
+                            return res.status(403).json({ error: "Path not allowed by token access rules" });
+                        }
+                        handler(req, res);
+                    }
+                    catch (err) {
+                        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);
+                    try {
+                        const decoded = jwt.verify(token, process.env.JWT_SECRET || this.options.jwtSecret);
+                        const accessRules = Array.isArray(decoded?.accessRules)
+                            ? decoded.accessRules
+                            : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
+                                ? [decoded.pathFilter]
+                                : undefined);
+                        const allowed = Array.isArray(accessRules)
+                            ? accessRules.some((rule) => UnsTopicMatcher.matches(rule, fullPath))
+                            : false;
+                        if (!allowed) {
+                            return res.status(403).json({ error: "Path not allowed by token access rules" });
+                        }
+                        handler(req, res);
+                    }
+                    catch (err) {
+                        return res.status(401).json({ error: "Invalid token" });
+                    }
+                });
+            }
+            else {
+                this.app.router.get(fullPath, handler);
+            }
+            if (this.app.swaggerSpec) {
+                this.app.swaggerSpec.paths = this.app.swaggerSpec.paths || {};
+                this.app.swaggerSpec.paths[`/api${fullPath}`] = {
+                    get: {
+                        summary: options?.apiDescription || "No description",
+                        tags: options?.tags || [],
+                        parameters: (options?.queryParams || []).map((p) => ({
+                            name: p.name,
+                            in: "query",
+                            required: !!p.required,
+                            schema: { type: p.type },
+                            description: p.description,
+                        })),
+                        responses: {
+                            "200": { description: "OK" },
+                            "400": { description: "Bad Request" },
+                            "401": { description: "Unauthorized" },
+                            "403": { description: "Forbidden" },
+                        },
+                    },
+                };
+            }
+        }
+        catch (error) {
+            logger.error(`${this.instanceNameWithSuffix} - Error publishing message to topic ${topic}${attribute}: ${error.message}`);
+        }
+    }
+    post(..._args) {
+        // Implement POST logic or route binding here
+        return "POST called";
+    }
+    extractBearerToken(req, res) {
+        const authHeader = req.headers["authorization"];
+        if (!authHeader || !authHeader.startsWith("Bearer ")) {
+            res.status(401).json({ error: "Missing or invalid Authorization header" });
+            return undefined;
+        }
+        return authHeader.slice(7);
+    }
+    async getPublicKeyFromJwks(token) {
+        // Decode header to get kid
+        const decoded = jwt.decode(token, { complete: true });
+        const kid = decoded?.header?.kid;
+        const keys = await this.fetchJwksKeys();
+        let jwk = kid ? keys.find((k) => k.kid === kid) : undefined;
+        // If no kid match and activeKidUrl configured, try that
+        if (!jwk && this.options?.jwks?.activeKidUrl) {
+            try {
+                const resp = await fetch(this.options.jwks.activeKidUrl);
+                if (resp.ok) {
+                    const activeKid = await resp.text();
+                    jwk = keys.find((k) => k.kid === activeKid.trim());
+                }
+            }
+            catch (_) {
+                // ignore and fall through
+            }
+        }
+        // If still not found but only one key, use it
+        if (!jwk && keys.length === 1) {
+            jwk = keys[0];
+        }
+        if (!jwk) {
+            throw new Error("Signing key not found in JWKS");
+        }
+        // Prefer x5c certificate if provided
+        if (Array.isArray(jwk.x5c) && jwk.x5c.length > 0) {
+            return this.certFromX5c(jwk.x5c[0]);
+        }
+        // Build PEM from JWK (RSA)
+        if (jwk.kty === "RSA" && jwk.n && jwk.e) {
+            const keyObj = createPublicKey({ key: { kty: "RSA", n: jwk.n, e: jwk.e }, format: "jwk" });
+            return keyObj.export({ type: "spki", format: "pem" }).toString();
+        }
+        throw new Error("Unsupported JWK format");
+    }
+    async fetchJwksKeys() {
+        const ttl = this.options?.jwks?.cacheTtlMs ?? 5 * 60 * 1000; // default 5 minutes
+        const now = Date.now();
+        if (this.jwksCache && now - this.jwksCache.fetchedAt < ttl) {
+            return this.jwksCache.keys;
+        }
+        const url = this.options.jwks.wellKnownJwksUrl;
+        const resp = await fetch(url);
+        if (!resp.ok) {
+            throw new Error(`Failed to fetch JWKS (${resp.status})`);
+        }
+        const body = await resp.json();
+        const keys = Array.isArray(body?.keys) ? body.keys : [];
+        this.jwksCache = { keys, fetchedAt: now };
+        return keys;
+    }
+    certFromX5c(x5cFirst) {
+        const pemBody = x5cFirst.match(/.{1,64}/g)?.join("\n") ?? x5cFirst;
+        return `-----BEGIN CERTIFICATE-----\n${pemBody}\n-----END CERTIFICATE-----\n`;
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@uns-kit/api",
+  "version": "0.0.1",
+  "description": "Express-powered API gateway plugin for UnsProxyProcess with JWT/JWKS support.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aljoša Vister <aljosa.vister@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uns-datahub/uns-kit.git",
+    "directory": "packages/uns-api"
+  },
+  "keywords": [
+    "uns",
+    "api",
+    "express",
+    "http",
+    "mqtt",
+    "typescript"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./*": "./dist/*"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@uns-kit/core": "^0.0.1",
+    "jsonwebtoken": "^9.0.2",
+    "cookie-parser": "^1.4.7",
+    "express": "^5.1.0",
+    "multer": "^2.0.2"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/cookie-parser": "^1.4.9",
+    "@types/express": "^5.0.3",
+    "@types/multer": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}