c8y-nitro 0.1.0

package/dist/utils/credentials.d.mts

@@ -0,0 +1,66 @@
+import { ICredentials } from "@c8y/client";
+
+//#region src/utils/credentials.d.ts
+/**
+ * Fetches credentials for all tenants subscribed to this microservice.\
+ * Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
+ * Results are cached for 10 minutes.\
+ * @returns Object mapping tenant IDs to their respective credentials
+ * @example
+ * // Get all subscribed tenant credentials:
+ * const credentials = await useSubscribedTenantCredentials()
+ * console.log(Object.keys(credentials)) // ['t12345', 't67890']
+ *
+ * // Access specific tenant:
+ * const tenant1Creds = credentials['t12345']
+ *
+ * // Invalidate cache:
+ * await useSubscribedTenantCredentials.invalidate()
+ *
+ * // Force refresh:
+ * const freshCreds = await useSubscribedTenantCredentials.refresh()
+ */
+declare const useSubscribedTenantCredentials: (() => Promise<Record<string, ICredentials>>) & {
+  invalidate: () => Promise<void>;
+  refresh: () => Promise<Record<string, ICredentials>>;
+};
+/**
+ * Fetches credentials for the tenant where this microservice is deployed.\
+ * Uses the C8Y_BOOTSTRAP_TENANT environment variable to identify the deployed tenant.\
+ * Returns credentials from the subscribed tenant credentials cache (cached for 10 minutes).
+ * @returns Credentials for the deployed tenant
+ * @throws {HTTPError} If no credentials found for the deployed tenant
+ * @example
+ * // Get deployed tenant credentials:
+ * const creds = await useDeployedTenantCredentials()
+ * console.log(creds.tenant, creds.user)
+ *
+ * // Invalidate cache:
+ * await useDeployedTenantCredentials.invalidate()
+ *
+ * // Force refresh:
+ * const freshCreds = await useDeployedTenantCredentials.refresh()
+ * @note This function is not cached separately. It uses the cache of `useSubscribedTenantCredentials()`. Invalidating or refreshing one will refresh `useDeployedTenantCredentials()`s cache.
+ */
+declare const useDeployedTenantCredentials: (() => Promise<ICredentials>) & {
+  invalidate: () => Promise<void>;
+  refresh: () => Promise<ICredentials>;
+};
+/**
+ * Fetches credentials for the tenant of the current user making the request.\
+ * Extracts the user's tenant ID from the request headers and returns corresponding credentials.\
+ * Results are cached in the request context for subsequent calls within the same request.\
+ * Must be called within a request handler context.
+ * @returns Credentials for the user's tenant
+ * @throws {HTTPError} If no subscribed tenant credentials found for the user's tenant
+ * @example
+ * // In a request handler:
+ * const userCreds = await useUserTenantCredentials()
+ * console.log(userCreds.tenant, userCreds.user)
+ *
+ * // Credentials are automatically cached for the request duration
+ * const sameCreds = await useUserTenantCredentials() // Uses cached value
+ */
+declare function useUserTenantCredentials(): Promise<ICredentials>;
+//#endregion
+export { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTenantCredentials };

package/dist/utils/credentials.mjs

@@ -0,0 +1,117 @@
+import { useUserClient } from "./client.mjs";
+import process from "node:process";
+import { Client } from "@c8y/client";
+import { useRequest } from "nitro/context";
+import { defineCachedFunction } from "nitro/cache";
+import { HTTPError } from "nitro/h3";
+import { useStorage } from "nitro/storage";
+
+//#region src/utils/credentials.ts
+/**
+* Fetches credentials for all tenants subscribed to this microservice.\
+* Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
+* Results are cached for 10 minutes.\
+* @returns Object mapping tenant IDs to their respective credentials
+* @example
+* // Get all subscribed tenant credentials:
+* const credentials = await useSubscribedTenantCredentials()
+* console.log(Object.keys(credentials)) // ['t12345', 't67890']
+*
+* // Access specific tenant:
+* const tenant1Creds = credentials['t12345']
+*
+* // Invalidate cache:
+* await useSubscribedTenantCredentials.invalidate()
+*
+* // Force refresh:
+* const freshCreds = await useSubscribedTenantCredentials.refresh()
+*/
+const useSubscribedTenantCredentials = Object.assign(defineCachedFunction(async () => {
+	return (await Client.getMicroserviceSubscriptions({
+		tenant: process.env.C8Y_BOOTSTRAP_TENANT,
+		user: process.env.C8Y_BOOTSTRAP_USER,
+		password: process.env.C8Y_BOOTSTRAP_PASSWORD
+	}, process.env.C8Y_BASEURL)).reduce((acc, cred) => {
+		if (cred.tenant) acc[cred.tenant] = cred;
+		return acc;
+	}, {});
+}, {
+	maxAge: 600,
+	name: "_c8y_nitro_get_subscribed_tenant_credentials",
+	group: "c8y_nitro",
+	swr: false
+}), {
+	invalidate: async () => {
+		await useStorage("cache").removeItem(`c8y_nitro:functions:_c8y_nitro_get_subscribed_tenant_credentials.json`);
+	},
+	refresh: async () => {
+		await useSubscribedTenantCredentials.invalidate();
+		return await useSubscribedTenantCredentials();
+	}
+});
+/**
+* Fetches credentials for the tenant where this microservice is deployed.\
+* Uses the C8Y_BOOTSTRAP_TENANT environment variable to identify the deployed tenant.\
+* Returns credentials from the subscribed tenant credentials cache (cached for 10 minutes).
+* @returns Credentials for the deployed tenant
+* @throws {HTTPError} If no credentials found for the deployed tenant
+* @example
+* // Get deployed tenant credentials:
+* const creds = await useDeployedTenantCredentials()
+* console.log(creds.tenant, creds.user)
+*
+* // Invalidate cache:
+* await useDeployedTenantCredentials.invalidate()
+*
+* // Force refresh:
+* const freshCreds = await useDeployedTenantCredentials.refresh()
+* @note This function is not cached separately. It uses the cache of `useSubscribedTenantCredentials()`. Invalidating or refreshing one will refresh `useDeployedTenantCredentials()`s cache.
+*/
+const useDeployedTenantCredentials = Object.assign(async () => {
+	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
+	const allCredsPromise = await useSubscribedTenantCredentials();
+	if (!allCredsPromise[tenant]) throw new HTTPError({
+		message: `No credentials found for tenant deployed tenant '${tenant}'`,
+		status: 500,
+		statusText: "Internal Server Error"
+	});
+	return allCredsPromise[tenant];
+}, {
+	invalidate: useSubscribedTenantCredentials.invalidate,
+	refresh: async () => {
+		await useDeployedTenantCredentials.invalidate();
+		return await useDeployedTenantCredentials();
+	}
+});
+/**
+* Fetches credentials for the tenant of the current user making the request.\
+* Extracts the user's tenant ID from the request headers and returns corresponding credentials.\
+* Results are cached in the request context for subsequent calls within the same request.\
+* Must be called within a request handler context.
+* @returns Credentials for the user's tenant
+* @throws {HTTPError} If no subscribed tenant credentials found for the user's tenant
+* @example
+* // In a request handler:
+* const userCreds = await useUserTenantCredentials()
+* console.log(userCreds.tenant, userCreds.user)
+*
+* // Credentials are automatically cached for the request duration
+* const sameCreds = await useUserTenantCredentials() // Uses cached value
+*/
+async function useUserTenantCredentials() {
+	const request = useRequest();
+	if (request.context?.["c8y_user_tenant_credentials"]) return request.context["c8y_user_tenant_credentials"];
+	const tenantId = useUserClient().core.tenant;
+	const userTenantCreds = (await useSubscribedTenantCredentials())[tenantId];
+	if (!userTenantCreds) throw new HTTPError({
+		message: `No subscribed tenant credentials found for user tenant '${tenantId}'`,
+		status: 500,
+		statusText: "Internal Server Error"
+	});
+	request.context ??= {};
+	request.context["c8y_user_tenant_credentials"] = userTenantCreds;
+	return userTenantCreds;
+}
+
+//#endregion
+export { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTenantCredentials };

package/dist/utils/internal/common.mjs

@@ -0,0 +1,26 @@
+//#region src/utils/internal/common.ts
+/**
+* Converts undici Request headers to the format expected by MicroserviceClientRequestAuth.\
+* Extracts the following headers from the request:
+* - `authorization`: Used for Basic Auth or Bearer token authentication
+* - `cookie`: Used to extract XSRF-TOKEN and authorization token from cookies
+*
+* The MicroserviceClientRequestAuth class will automatically:
+* - Extract XSRF-TOKEN from cookies for CSRF protection
+* - Extract authorization token from cookies (prioritized over header auth)
+* - Fall back to Authorization header if no cookie-based auth is present
+*
+* @param request - The HTTP request containing headers
+* @returns Headers object compatible with \@c8y/client's MicroserviceClientRequestAuth
+*/
+function convertRequestHeadersToC8yFormat(request) {
+	const headers = {};
+	const authorization = request.headers.get("authorization");
+	if (authorization) headers.authorization = authorization;
+	const cookie = request.headers.get("cookie");
+	if (cookie) headers.cookie = cookie;
+	return headers;
+}
+
+//#endregion
+export { convertRequestHeadersToC8yFormat };

package/dist/utils/middleware.d.mts

@@ -0,0 +1,89 @@
+import { EventHandler } from "nitro/h3";
+import { C8YRoles } from "c8y-nitro/types";
+
+//#region src/utils/middleware.d.ts
+type UserRole = keyof C8YRoles | (string & {});
+/**
+ * Middleware to check if the current user has the required role.\
+ * If the user doesn't have the required role, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param role - Single role ID to check for
+ * @returns Event handler that validates user roles
+ * @example
+ * // Single role:
+ * export default defineHandler({
+ *  middleware: [hasUserRequiredRole('ROLE_INVENTORY_ADMIN')],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ *
+ */
+declare function hasUserRequiredRole(role: UserRole): EventHandler;
+/**
+ * Middleware to check if the current user has at least one of the required roles.\
+ * If the user doesn't have any of the required roles, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param roles - Array of role IDs to check for
+ * @returns Event handler that validates user roles
+ * @example
+ * // Multiple roles:
+ * export default defineHandler({
+ *  middleware: [hasUserRequiredRole(['ROLE_INVENTORY_ADMIN', 'ROLE_DEVICE_CONTROL'])],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ */
+declare function hasUserRequiredRole(roles: UserRole[]): EventHandler;
+/**
+ * Middleware to check if the current user belongs to a specific allowed tenant.\
+ * If the user's tenant doesn't match, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param tenantId - Single tenant ID to allow
+ * @returns Event handler that validates user tenant
+ * @example
+ * // Single tenant:
+ * export default defineHandler({
+ *  middleware: [isUserFromAllowedTenant('t123456')],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ *
+ */
+declare function isUserFromAllowedTenant(tenantId: string): EventHandler;
+/**
+ * Middleware to check if the current user belongs to one of the allowed tenants.\
+ * If the user's tenant doesn't match any of the allowed tenants, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param tenantIds - Array of tenant IDs to allow
+ * @returns Event handler that validates user tenant
+ * @example
+ * // Multiple tenants:
+ * export default defineHandler({
+ *  middleware: [isUserFromAllowedTenant(['t123456', 't789012'])],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ */
+declare function isUserFromAllowedTenant(tenantIds: string[]): EventHandler;
+/**
+ * Middleware to check if the current user belongs to the deployed tenant.\
+ * The deployed tenant is where this microservice is hosted (C8Y_BOOTSTRAP_TENANT).\
+ * If the user's tenant doesn't match the deployed tenant, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @returns Event handler that validates user is from deployed tenant
+ * @example
+ * // Only allow users from the deployed tenant:
+ * export default defineHandler({
+ *  middleware: [isUserFromDeployedTenant()],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ */
+declare function isUserFromDeployedTenant(): EventHandler;
+//#endregion
+export { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant };

package/dist/utils/middleware.mjs

@@ -0,0 +1,62 @@
+import { useUserClient } from "./client.mjs";
+import { useUserRoles } from "./resources.mjs";
+import process from "node:process";
+import { HTTPError, defineHandler } from "nitro/h3";
+
+//#region src/utils/middleware.ts
+function hasUserRequiredRole(roleOrRoles) {
+	return defineHandler(async () => {
+		const requiredRoles = Array.isArray(roleOrRoles) ? roleOrRoles : [roleOrRoles];
+		const userRoles = await useUserRoles();
+		if (!requiredRoles.some((role) => userRoles.includes(role))) throw new HTTPError({
+			status: 403,
+			statusText: "Forbidden",
+			message: `User does not have required role(s) to access this resource: ${requiredRoles.join(", ")}`
+		});
+	});
+}
+function isUserFromAllowedTenant(tenantIdOrIds) {
+	return defineHandler(async () => {
+		const allowedTenants = Array.isArray(tenantIdOrIds) ? tenantIdOrIds : [tenantIdOrIds];
+		const userTenantId = useUserClient().core.tenant;
+		if (!allowedTenants.includes(userTenantId)) throw new HTTPError({
+			status: 403,
+			statusText: "Forbidden",
+			message: `User's tenant '${userTenantId}' is not allowed to access this resource. Allowed tenants: ${allowedTenants.join(", ")}`
+		});
+	});
+}
+/**
+* Middleware to check if the current user belongs to the deployed tenant.\
+* The deployed tenant is where this microservice is hosted (C8Y_BOOTSTRAP_TENANT).\
+* If the user's tenant doesn't match the deployed tenant, throws a 403 Forbidden error.\
+* Must be used within a request handler context.\
+* @returns Event handler that validates user is from deployed tenant
+* @example
+* // Only allow users from the deployed tenant:
+* export default defineHandler({
+*  middleware: [isUserFromDeployedTenant()],
+*  handler: async () => {
+*   return { message: 'You have access' }
+*  }
+* })
+*/
+function isUserFromDeployedTenant() {
+	return defineHandler(async () => {
+		const userTenantId = useUserClient().core.tenant;
+		const deployedTenantId = process.env.C8Y_BOOTSTRAP_TENANT;
+		if (!deployedTenantId) throw new HTTPError({
+			status: 500,
+			statusText: "Internal Server Error",
+			message: "C8Y_BOOTSTRAP_TENANT environment variable is not set"
+		});
+		if (userTenantId !== deployedTenantId) throw new HTTPError({
+			status: 403,
+			statusText: "Forbidden",
+			message: `Only users from tenant '${deployedTenantId}' can access this resource.`
+		});
+	});
+}
+
+//#endregion
+export { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant };

package/dist/utils/resources.d.mts

@@ -0,0 +1,28 @@
+import { ICurrentUser } from "@c8y/client";
+
+//#region src/utils/resources.d.ts
+/**
+ * Fetches the current user from Cumulocity using credentials extracted from the current request's headers.
+ * This is a non-cached version - fetches fresh data on every call.
+ * Must be called within a request handler context.
+ * @returns The current user object from Cumulocity
+ * @example
+ * // In a request handler:
+ * const user = await useUser()
+ * console.log(user.userName, user.email)
+ */
+declare function useUser(): Promise<ICurrentUser>;
+/**
+ * Fetches the roles of the current user from Cumulocity.
+ * Internally calls `useUser()` and extracts role IDs from the user object.
+ * This is a non-cached version - fetches fresh data on every call.
+ * Must be called within a request handler context.
+ * @returns Array of role ID strings assigned to the current user
+ * @example
+ * // In a request handler:
+ * const roles = await useUserRoles()
+ * console.log(roles) // ['ROLE_INVENTORY_READ', 'ROLE_INVENTORY_ADMIN']
+ */
+declare function useUserRoles(): Promise<string[]>;
+//#endregion
+export { useUser, useUserRoles };

package/dist/utils/resources.mjs

@@ -0,0 +1,50 @@
+import { useUserClient } from "./client.mjs";
+import { useRequest } from "nitro/context";
+import { HTTPError } from "nitro/h3";
+
+//#region src/utils/resources.ts
+/**
+* Fetches the current user from Cumulocity using credentials extracted from the current request's headers.
+* This is a non-cached version - fetches fresh data on every call.
+* Must be called within a request handler context.
+* @returns The current user object from Cumulocity
+* @example
+* // In a request handler:
+* const user = await useUser()
+* console.log(user.userName, user.email)
+*/
+async function useUser() {
+	const request = useRequest();
+	if (request.context?.["c8y_user"]) return request.context["c8y_user"];
+	const { res, data: user } = await useUserClient().user.currentWithEffectiveRoles();
+	if (!res.ok) throw new HTTPError({
+		message: `Failed to fetch current user`,
+		status: res.status,
+		statusText: res.statusText
+	});
+	request.context ??= {};
+	request.context["c8y_user"] = user;
+	return user;
+}
+/**
+* Fetches the roles of the current user from Cumulocity.
+* Internally calls `useUser()` and extracts role IDs from the user object.
+* This is a non-cached version - fetches fresh data on every call.
+* Must be called within a request handler context.
+* @returns Array of role ID strings assigned to the current user
+* @example
+* // In a request handler:
+* const roles = await useUserRoles()
+* console.log(roles) // ['ROLE_INVENTORY_READ', 'ROLE_INVENTORY_ADMIN']
+*/
+async function useUserRoles() {
+	const request = useRequest();
+	if (request.context?.["c8y_user_roles"]) return request.context["c8y_user_roles"];
+	const userRoles = (await useUser()).effectiveRoles?.map((role) => role.name) ?? [];
+	request.context ??= {};
+	request.context["c8y_user_roles"] = userRoles;
+	return userRoles;
+}
+
+//#endregion
+export { useUser, useUserRoles };

package/dist/utils.d.mts

@@ -0,0 +1,5 @@
+import { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, useUserTenantClient } from "./utils/client.mjs";
+import { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant } from "./utils/middleware.mjs";
+import { useUser, useUserRoles } from "./utils/resources.mjs";
+import { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTenantCredentials } from "./utils/credentials.mjs";
+export { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useSubscribedTenantClients, useSubscribedTenantCredentials, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/dist/utils.mjs

@@ -0,0 +1,6 @@
+import { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTenantCredentials } from "./utils/credentials.mjs";
+import { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, useUserTenantClient } from "./utils/client.mjs";
+import { useUser, useUserRoles } from "./utils/resources.mjs";
+import { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant } from "./utils/middleware.mjs";
+
+export { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useSubscribedTenantClients, useSubscribedTenantCredentials, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "c8y-nitro",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
+  "keywords": [
+    "cumulocity",
+    "c8y",
+    "microservice",
+    "nitro",
+    "typescript",
+    "iot",
+    "docker"
+  ],
+  "license": "MIT",
+  "author": "schplitt",
+  "homepage": "https://github.com/schplitt/c8y-nitro#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/schplitt/c8y-nitro.git"
+  },
+  "bugs": {
+    "url": "https://github.com/schplitt/c8y-nitro/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/types.mjs"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.mts",
+      "import": "./dist/utils.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "c8y-nitro": "./dist/cli/index.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "dependencies": {
+    "c12": "^3.3.3",
+    "citty": "^0.2.0",
+    "consola": "^3.4.2",
+    "jszip": "^3.10.1",
+    "pathe": "^2.0.3",
+    "pkg-types": "^2.3.0",
+    "spinnies": "^0.5.1",
+    "tinyexec": "^1.0.2"
+  },
+  "devDependencies": {
+    "@schplitt/eslint-config": "^1.2.0",
+    "@types/spinnies": "^0.5.3",
+    "bumpp": "^10.4.0",
+    "eslint": "^9.39.2",
+    "memfs": "^4.56.10",
+    "tsdown": "^0.20.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@c8y/client": ">=1021.0.0",
+    "nitro": "v3.0.1-alpha.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "typecheck": "tsc --noEmit",
+    "prerelease": "eslint && tsc --noEmit && tsdown",
+    "release": "bumpp",
+    "test": "vitest"
+  }
+}