c8y-nitro 0.7.0 → 0.7.2

package/dist/autoBootstrap-Drk7ltXK.mjs

@@ -0,0 +1,212 @@
+import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-DscUs-Kd.mjs";
+import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
+import { join } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import process from "node:process";
+//#region src/module/manifestCache.ts
+/**
+* Directory (inside the project's `node_modules`) where c8y-nitro persists
+* local dev state such as the last-synced manifest hash. Lives in
+* `node_modules` so it is naturally gitignored and scoped per-checkout.
+*/
+const CACHE_DIR_SEGMENTS = ["node_modules", ".c8y-nitro"];
+const CACHE_FILE_NAME = "bootstrap-state.json";
+const CACHE_SCHEMA_VERSION = 1;
+function getCacheDir(rootDir) {
+	return join(rootDir, ...CACHE_DIR_SEGMENTS);
+}
+function getCacheFile(rootDir) {
+	return join(getCacheDir(rootDir), CACHE_FILE_NAME);
+}
+/**
+* Compute a hash over the manifest and the deployment target it will be synced
+* to. Folding the target in means switching tenant/baseURL invalidates the
+* cached hash even if the manifest itself is unchanged.
+*
+* @param manifest - The generated Cumulocity manifest
+* @param target - The deployment target identity
+*/
+function hashManifest(manifest, target) {
+	const payload = JSON.stringify({
+		manifest,
+		target
+	});
+	return createHash("sha256").update(payload).digest("hex");
+}
+/**
+* Read the persisted bootstrap state, or `null` when absent, unreadable, or
+* from an incompatible schema version.
+* @param rootDir - Project root directory (containing `node_modules`)
+*/
+async function readManifestCache(rootDir) {
+	try {
+		const content = await readFile(getCacheFile(rootDir), "utf-8");
+		const state = JSON.parse(content);
+		if (state.schemaVersion !== CACHE_SCHEMA_VERSION) return null;
+		return state;
+	} catch {
+		return null;
+	}
+}
+/**
+* Persist the bootstrap state for future dev restarts.
+* @param rootDir - Project root directory (containing `node_modules`)
+* @param state - The state to persist (schema version is filled in automatically)
+*/
+async function writeManifestCache(rootDir, state) {
+	await mkdir(getCacheDir(rootDir), { recursive: true });
+	const payload = {
+		schemaVersion: CACHE_SCHEMA_VERSION,
+		...state
+	};
+	await writeFile(getCacheFile(rootDir), JSON.stringify(payload, null, 2), "utf-8");
+}
+//#endregion
+//#region src/module/autoBootstrap.ts
+const BOOTSTRAP_ENV_VARS = [
+	"C8Y_BOOTSTRAP_TENANT",
+	"C8Y_BOOTSTRAP_USER",
+	"C8Y_BOOTSTRAP_PASSWORD"
+];
+const DEV_ENV_VARS = [
+	"C8Y_BASEURL",
+	"C8Y_DEVELOPMENT_TENANT",
+	"C8Y_DEVELOPMENT_USER",
+	"C8Y_DEVELOPMENT_PASSWORD"
+];
+/**
+* Reads bootstrap credentials from an env object (e.g. a loaded `.env` file or
+* `process.env`). Returns `undefined` unless all three variables are present.
+* @param env - Environment variables object
+*/
+function readBootstrapCredentialsFromEnv(env) {
+	const tenant = env.C8Y_BOOTSTRAP_TENANT;
+	const name = env.C8Y_BOOTSTRAP_USER;
+	const password = env.C8Y_BOOTSTRAP_PASSWORD;
+	if (!tenant || !name || !password) return;
+	return {
+		tenant,
+		name,
+		password
+	};
+}
+/**
+* Verifies the microservice on the development tenant and keeps it in sync with
+* the local manifest, bootstrapping (or re-bootstrapping) when needed.
+*
+* Unlike a purely env-var-based check, this always verifies against the tenant,
+* so it also handles:
+* - the manifest changing between runs (auto-updates a placeholder), and
+* - the application being deleted on the tenant while stale bootstrap env vars
+*   still linger locally (re-creates it).
+*
+* A previously *deployed* microservice (one with an active version) is never
+* overwritten automatically - we only warn about the drift.
+*
+* @param options - See {@link SyncBootstrappedMicroserviceOptions}
+* @returns The bootstrap credentials for the microservice (freshly fetched when
+* they were refreshed, otherwise the ones already present in `env`)
+*/
+async function syncBootstrappedMicroservice(options) {
+	const { rootDir, baseUrl, developmentTenant, authHeader, manifest, logger } = options;
+	const env = options.env ?? process.env;
+	const target = {
+		baseUrl,
+		developmentTenant,
+		name: manifest.name
+	};
+	const currentHash = hashManifest(manifest, target);
+	const existingApp = await findMicroserviceByName(baseUrl, manifest.name, authHeader);
+	if (!existingApp) {
+		const createdApp = await createMicroservice(baseUrl, manifest, authHeader);
+		logger.debug(`Microservice "${manifest.name}" created (ID: ${createdApp.id})`);
+		const credentials = await finalizeBootstrap({
+			rootDir,
+			logger,
+			baseUrl,
+			developmentTenant,
+			appId: createdApp.id,
+			authHeader,
+			target,
+			manifestHash: currentHash,
+			forceCredentials: true
+		});
+		logger.success(`Microservice "${manifest.name}" created on the development tenant.`);
+		return credentials;
+	}
+	const appId = existingApp.id;
+	const isRealService = Boolean(existingApp.activeVersionId);
+	const cache = await readManifestCache(rootDir);
+	if (!cache || cache.manifestHash !== currentHash || cache.appId !== appId) if (isRealService) logger.warn(`Local manifest for "${manifest.name}" differs from the deployed microservice on the development tenant. The running service was left untouched. Redeploy or run \`npx c8y-nitro bootstrap\` to update it explicitly.`);
+	else {
+		await updateMicroservice(baseUrl, appId, manifest, authHeader);
+		logger.success(`Updated microservice "${manifest.name}" with changed manifest.`);
+	}
+	const hasBootstrapCreds = BOOTSTRAP_ENV_VARS.every((v) => env[v]);
+	const appChanged = cache?.appId !== appId;
+	return await finalizeBootstrap({
+		rootDir,
+		logger,
+		baseUrl,
+		developmentTenant,
+		appId,
+		authHeader,
+		target,
+		manifestHash: currentHash,
+		forceCredentials: !hasBootstrapCreds || appChanged
+	}) ?? readBootstrapCredentialsFromEnv(env);
+}
+/**
+* Verifies the microservice on the development tenant during dev startup.
+* Runs silently unless a bootstrap/sync was performed or an error occurs.
+* @param nitro - Nitro instance
+*/
+async function autoBootstrap(nitro) {
+	try {
+		if (DEV_ENV_VARS.filter((v) => !process.env[v]).length > 0) return;
+		const baseUrl = process.env.C8Y_BASEURL.endsWith("/") ? process.env.C8Y_BASEURL.slice(0, -1) : process.env.C8Y_BASEURL;
+		const authHeader = createBasicAuthHeader(process.env.C8Y_DEVELOPMENT_TENANT, process.env.C8Y_DEVELOPMENT_USER, process.env.C8Y_DEVELOPMENT_PASSWORD);
+		const manifest = await createC8yManifest(nitro.options.rootDir, nitro.options, nitro.logger);
+		await syncBootstrappedMicroservice({
+			rootDir: nitro.options.rootDir,
+			baseUrl,
+			developmentTenant: process.env.C8Y_DEVELOPMENT_TENANT,
+			authHeader,
+			manifest,
+			logger: nitro.logger
+		});
+	} catch (error) {
+		nitro.logger.warn("Auto-bootstrap failed:", error instanceof Error ? error.message : String(error));
+	}
+}
+/**
+* Subscribe the tenant, optionally (re)write bootstrap credentials, and persist
+* the synced state to the local cache.
+* @param opts - Bootstrap finalization inputs
+* @returns The freshly fetched credentials when `forceCredentials` was set
+*/
+async function finalizeBootstrap(opts) {
+	await subscribeToApplication(opts.baseUrl, opts.developmentTenant, opts.appId, opts.authHeader);
+	let credentials;
+	if (opts.forceCredentials) {
+		credentials = await getBootstrapCredentials(opts.baseUrl, opts.appId, opts.authHeader);
+		const envFileName = await writeBootstrapCredentials(opts.rootDir, {
+			C8Y_BOOTSTRAP_TENANT: credentials.tenant,
+			C8Y_BOOTSTRAP_USER: credentials.name,
+			C8Y_BOOTSTRAP_PASSWORD: credentials.password
+		});
+		process.env.C8Y_BOOTSTRAP_TENANT = credentials.tenant;
+		process.env.C8Y_BOOTSTRAP_USER = credentials.name;
+		process.env.C8Y_BOOTSTRAP_PASSWORD = credentials.password;
+		opts.logger.debug(`Bootstrap credentials written to ${envFileName}`);
+	}
+	await writeManifestCache(opts.rootDir, {
+		manifestHash: opts.manifestHash,
+		target: opts.target,
+		appId: opts.appId
+	});
+	return credentials;
+}
+//#endregion
+export { readBootstrapCredentialsFromEnv as n, syncBootstrappedMicroservice as r, autoBootstrap as t };

package/dist/{bootstrap-ObaEF7rN.mjs → bootstrap-C1Qly0J_.mjs}

@@ -1,4 +1,4 @@
-import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-BFjK6AYb.mjs";
+import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-DscUs-Kd.mjs";
 import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
 import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
 import { defineCommand, runCommand } from "citty";
@@ -52,7 +52,7 @@ var bootstrap_default = defineCommand({
 		});
 		consola.success(`Bootstrap credentials written to ${envFileName}`);
 		if (manifest.roles && manifest.roles.length > 0) {
-			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-B58Fguop.mjs").then((r) => r.default), { rawArgs: [] });
+			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-B-DNuScZ.mjs").then((r) => r.default), { rawArgs: [] });
 		}
 		consola.success("Bootstrap complete!");
 	}

package/dist/{c8y-api-BFjK6AYb.mjs → c8y-api-DscUs-Kd.mjs}

@@ -283,14 +283,20 @@ async function unassignUserRole(baseUrl, tenantId, userId, roleId, authHeader) {
 	}
 }
 /**
-* Gets all tenant options for a specific category.
+* Fetches the current application's settings (the tenant options of the
+* microservice's own settings category) via
+* `GET /application/currentApplication/settings`.
+*
+* Must be called with microservice credentials (bootstrap or service user).
+* Unlike the Options API — which returns `credentials.*` values encrypted for
+* regular users and rejects the bootstrap user with `403` — this endpoint
+* returns encrypted `credentials.*` options **decrypted**.
 * @param baseUrl - The Cumulocity base URL
-* @param category - The category to fetch options for
-* @param authHeader - The Basic Auth header
-* @returns Record of key-value pairs for the category
+* @param authHeader - Basic Auth header of the bootstrap (or service) user
+* @returns Flat key-value map of the microservice's settings
 */
-async function getTenantOptionsByCategory(baseUrl, category, authHeader) {
-	const url = `${baseUrl}/tenant/options/${encodeURIComponent(category)}`;
+async function getCurrentApplicationSettings(baseUrl, authHeader) {
+	const url = `${baseUrl}/application/currentApplication/settings`;
 	const response = await fetch(url, {
 		method: "GET",
 		headers: {
@@ -298,23 +304,21 @@ async function getTenantOptionsByCategory(baseUrl, category, authHeader) {
 			Accept: "application/json"
 		}
 	});
-	if (response.status === 404) return {};
 	if (!response.ok) {
 		const errorText = await response.text();
-		throw new Error(`Failed to get tenant options for category ${category}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
+		throw new Error(`Failed to get current application settings: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
 	}
 	return await response.json();
 }
 /**
-* Gets a specific tenant option value.
+* Gets all tenant options for a specific category.
 * @param baseUrl - The Cumulocity base URL
-* @param category - The category of the option
-* @param key - The option key
+* @param category - The category to fetch options for
 * @param authHeader - The Basic Auth header
-* @returns The option value, or undefined if not set
+* @returns Record of key-value pairs for the category
 */
-async function getTenantOption(baseUrl, category, key, authHeader) {
-	const url = `${baseUrl}/tenant/options/${encodeURIComponent(category)}/${encodeURIComponent(key)}`;
+async function getTenantOptionsByCategory(baseUrl, category, authHeader) {
+	const url = `${baseUrl}/tenant/options/${encodeURIComponent(category)}`;
 	const response = await fetch(url, {
 		method: "GET",
 		headers: {
@@ -322,12 +326,12 @@ async function getTenantOption(baseUrl, category, key, authHeader) {
 			Accept: "application/json"
 		}
 	});
-	if (response.status === 404) return;
+	if (response.status === 404) return {};
 	if (!response.ok) {
 		const errorText = await response.text();
-		throw new Error(`Failed to get tenant option ${category}/${key}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
+		throw new Error(`Failed to get tenant options for category ${category}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
 	}
-	return (await response.json()).value;
+	return await response.json();
 }
 /**
 * Creates a tenant option.
@@ -420,4 +424,4 @@ async function deleteTenantOption(baseUrl, category, key, authHeader) {
 	}
 }
 //#endregion
-export { GENERATED_READINESS_ROUTE as _, findMicroserviceByName as a, getTenantOptionsByCategory as c, updateMicroservice as d, upsertTenantOption as f, GENERATED_LIVENESS_ROUTE as g, GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE as h, deleteTenantOption as i, subscribeToApplication as l, createC8yManifestFromNitro as m, createBasicAuthHeader as n, getBootstrapCredentials as o, createC8yManifest as p, createMicroservice as r, getTenantOption as s, assignUserRole as t, unassignUserRole as u };
+export { GENERATED_READINESS_ROUTE as _, findMicroserviceByName as a, getTenantOptionsByCategory as c, updateMicroservice as d, upsertTenantOption as f, GENERATED_LIVENESS_ROUTE as g, GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE as h, deleteTenantOption as i, subscribeToApplication as l, createC8yManifestFromNitro as m, createBasicAuthHeader as n, getBootstrapCredentials as o, createC8yManifest as p, createMicroservice as r, getCurrentApplicationSettings as s, assignUserRole as t, unassignUserRole as u };

package/dist/cli/index.mjs

@@ -1,4 +1,4 @@
-import { n as name, r as version, t as description } from "../package-BhFLRPOb.mjs";
+import { n as name, r as version, t as description } from "../package-BHOzdhHp.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/cli/index.ts
 runMain(defineCommand({
@@ -8,9 +8,9 @@ runMain(defineCommand({
 		description
 	},
 	subCommands: {
-		bootstrap: () => import("../bootstrap-ObaEF7rN.mjs").then((r) => r.default),
-		roles: () => import("../roles-B58Fguop.mjs").then((r) => r.default),
-		options: () => import("../options-B7_yb_wr.mjs").then((r) => r.default)
+		bootstrap: () => import("../bootstrap-C1Qly0J_.mjs").then((r) => r.default),
+		roles: () => import("../roles-B-DNuScZ.mjs").then((r) => r.default),
+		options: () => import("../options-CmLpZ3Qf.mjs").then((r) => r.default)
 	}
 }));
 //#endregion

package/dist/client-D0Tdq7H1.mjs

@@ -0,0 +1,280 @@
+import { t as createError } from "./logging-BUYT8Z2V.mjs";
+import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
+import { defineCachedFunction } from "nitro/cache";
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes } from "node:crypto";
+import process from "node:process";
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { useNitroHooks } from "nitro/app";
+//#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
+//#region src/utils/internal/tenant.ts
+const USER_TENANT_CACHE_SALT = randomBytes(32).toString("hex");
+function getCookieValue(cookieHeader, name) {
+	try {
+		const value = cookieHeader?.match(`(^|;)\\s*${name}\\s*=\\s*([^;]+)`);
+		return value ? value.pop() : void 0;
+	} catch {
+		return;
+	}
+}
+function getCurrentUserTenantCacheKeyMaterial(requestOrEvent) {
+	const request = "req" in requestOrEvent ? requestOrEvent.req : requestOrEvent;
+	const cookieAuth = getCookieValue(request.headers.get("cookie"), "authorization");
+	if (cookieAuth) return `cookie:${cookieAuth}`;
+	const authorization = request.headers.get("authorization");
+	if (authorization) return `header:${authorization}`;
+}
+function createCurrentUserTenantCacheKey(requestOrEvent) {
+	const material = getCurrentUserTenantCacheKeyMaterial(requestOrEvent);
+	if (!material) throw new Error("Cannot create current user tenant cache key without auth material");
+	return createHash("sha256").update(USER_TENANT_CACHE_SALT).update(":").update(material).digest("hex");
+}
+function tryGetTenantFromBasicAuth(requestOrEvent) {
+	const authorization = ("req" in requestOrEvent ? requestOrEvent.req : requestOrEvent).headers.get("authorization");
+	if (!authorization?.startsWith("Basic ")) return;
+	try {
+		const decoded = Buffer.from(authorization.slice(6), "base64").toString("utf8");
+		const separatorIndex = decoded.indexOf(":");
+		const userPart = separatorIndex === -1 ? decoded : decoded.slice(0, separatorIndex);
+		const slashIndex = userPart.indexOf("/");
+		if (slashIndex <= 0) return;
+		return userPart.slice(0, slashIndex);
+	} catch {
+		return;
+	}
+}
+const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
+	const basicTenant = tryGetTenantFromBasicAuth(requestOrEvent);
+	if (basicTenant) return basicTenant;
+	return (await useUserClient(requestOrEvent).tenant.current()).data.name;
+}, {
+	maxAge: 60,
+	name: "_c8y_nitro_get_current_user_tenant_id",
+	group: "c8y_nitro",
+	swr: false,
+	getKey: (requestOrEvent) => createCurrentUserTenantCacheKey(requestOrEvent),
+	shouldBypassCache: (requestOrEvent) => !getCurrentUserTenantCacheKeyMaterial(requestOrEvent)
+});
+const cachedTenantDomain = defineCachedFunction(async (requestOrEvent, _tenantId) => {
+	return (await useUserClient(requestOrEvent).tenant.current()).data.domainName;
+}, {
+	maxAge: 86400,
+	name: "_c8y_nitro_get_user_tenant_domain",
+	group: "c8y_nitro",
+	swr: false,
+	getKey: (_requestOrEvent, tenantId) => tenantId
+});
+/**
+* Resolves the public domain of the current user's tenant (e.g. `tenant.cumulocity.com`)
+* via `/tenant/currentTenant` with the user's credentials from the current request.
+* @param requestOrEvent - The H3Event or ServerRequest from the current request
+*/
+async function getUserTenantDomain(requestOrEvent) {
+	const tenantId = await getCurrentUserTenantId(requestOrEvent);
+	return cachedTenantDomain(requestOrEvent, tenantId);
+}
+const FAST_DOMAIN_SUCCESS_TTL = 6e4;
+const FAST_DOMAIN_FAILURE_TTL = 1e4;
+const FAST_DOMAIN_MAX_ENTRIES = 1e3;
+const fastDomainCache = /* @__PURE__ */ new Map();
+/**
+* Best-effort variant of {@link getUserTenantDomain} for per-request hot paths:
+* never throws (returns `undefined` for unauthenticated requests or failed
+* lookups) and memoizes results in-process per auth material. Failures are
+* cached briefly so requests with unresolvable credentials don't trigger a
+* platform call each time.
+* @param requestOrEvent - The H3Event or ServerRequest from the current request
+* @param resolveDomain - Domain resolver, only overridden in tests
+*/
+async function tryGetUserTenantDomainFast(requestOrEvent, resolveDomain = getUserTenantDomain) {
+	if (!getCurrentUserTenantCacheKeyMaterial(requestOrEvent)) return;
+	const key = createCurrentUserTenantCacheKey(requestOrEvent);
+	const now = Date.now();
+	const cached = fastDomainCache.get(key);
+	if (cached && cached.expiresAt > now) return cached.domain;
+	let domain;
+	try {
+		domain = await resolveDomain(requestOrEvent);
+	} catch {
+		domain = void 0;
+	}
+	if (!fastDomainCache.has(key) && fastDomainCache.size >= FAST_DOMAIN_MAX_ENTRIES) fastDomainCache.delete(fastDomainCache.keys().next().value);
+	fastDomainCache.set(key, {
+		domain,
+		expiresAt: now + (domain ? FAST_DOMAIN_SUCCESS_TTL : FAST_DOMAIN_FAILURE_TTL)
+	});
+	return domain;
+}
+/**
+* Builds the public URL a request is reachable at through the platform proxy:
+* `https://<tenant domain>/service/<contextPath><pathname><search>`.
+* The proxy strips the `/service/<contextPath>` prefix before the request
+* reaches the microservice, so it is re-added here.
+* @param tenantDomain - Public domain of the tenant (e.g. `tenant.cumulocity.com`)
+* @param contextPath - Context path of the microservice
+* @param url - URL the request was received with (only pathname and search are used)
+*/
+function buildPublicRequestUrl(tenantDomain, contextPath, url) {
+	return new URL(`https://${tenantDomain}/service/${contextPath}${url.pathname}${url.search}`);
+}
+//#endregion
+//#region src/utils/credentials.ts
+let prevCredentials = null;
+function shouldEmitTenantCredentialsUpdated(prev, next) {
+	if (!prev) return true;
+	const prevTenantIds = Object.keys(prev);
+	const nextTenantIds = Object.keys(next);
+	if (prevTenantIds.length !== nextTenantIds.length) return true;
+	return new Set(nextTenantIds).symmetricDifference(new Set(prevTenantIds)).size > 0;
+}
+/**
+* Fetches credentials for all tenants subscribed to this microservice.\
+* Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
+* Results are cached based on the configured TTL (default: 10 minutes).\
+* @returns Object mapping tenant IDs to their respective credentials
+* @config Cache TTL can be configured via:
+* - `c8y.cache.credentialsTTL` in the Nitro config (value in seconds)
+* - `NITRO_C8Y_CREDENTIALS_CACHE_TTL` environment variable
+* @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 cachedSubscribedTenantCredentials = defineCachedFunction(async () => {
+	const newCredentials = (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;
+	}, {});
+	if (shouldEmitTenantCredentialsUpdated(prevCredentials, newCredentials)) useNitroHooks().callHook("c8y:tenantCredentialsUpdated", prevCredentials, newCredentials);
+	prevCredentials = newCredentials;
+	return newCredentials;
+}, {
+	maxAge: useRuntimeConfig().c8yCredentialsCacheTTL ?? 600,
+	name: "_c8y_nitro_get_subscribed_tenant_credentials",
+	group: "c8y_nitro",
+	swr: false
+});
+const useSubscribedTenantCredentials = Object.assign(async () => {
+	const credentials = await cachedSubscribedTenantCredentials();
+	prevCredentials = credentials;
+	return credentials;
+}, {
+	invalidate: cachedSubscribedTenantCredentials.invalidate,
+	refresh: async () => {
+		await cachedSubscribedTenantCredentials.invalidate();
+		const credentials = await cachedSubscribedTenantCredentials();
+		prevCredentials = credentials;
+		return credentials;
+	}
+});
+/**
+* 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 based on configured TTL, default: 10 minutes).
+* @returns Credentials for the deployed tenant
+* @throws {EvlogError} 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 createError({
+		message: `No credentials found for tenant deployed tenant '${tenant}'`,
+		status: 500
+	});
+	return allCredsPromise[tenant];
+}, {
+	invalidate: useSubscribedTenantCredentials.invalidate,
+	refresh: async () => {
+		await useSubscribedTenantCredentials.refresh();
+		return await useDeployedTenantCredentials();
+	}
+});
+//#endregion
+//#region src/utils/client.ts
+/**
+* Creates a Cumulocity client authenticated with the current user's credentials.\
+* Extracts credentials from the Authorization header of the current request.
+* @param requestOrEvent - The H3Event or ServerRequest from the current request
+* @returns A configured Cumulocity Client instance
+* @example
+* // In a request handler:
+* const client = useUserClient(event)
+* const { data } = await client.inventory.list()
+*/
+function useUserClient(requestOrEvent) {
+	const request = "req" in requestOrEvent ? requestOrEvent.req : requestOrEvent;
+	if (request.context?.["c8y_user_client"]) return request.context["c8y_user_client"];
+	const client = new Client(new MicroserviceClientRequestAuth(convertRequestHeadersToC8yFormat(request)), process.env.C8Y_BASEURL);
+	request.context ??= {};
+	request.context["c8y_user_client"] = client;
+	return client;
+}
+/**
+* Creates a Cumulocity client for the tenant where this microservice is deployed.\
+* Uses the bootstrap tenant ID from runtime config to identify the deployed tenant.\
+* @returns A configured Cumulocity Client instance for the deployed tenant
+* @example
+* // Get client for the tenant hosting this microservice:
+* const client = await useDeployedTenantClient()
+* const { data } = await client.application.list()
+*/
+async function useDeployedTenantClient() {
+	const creds = await useSubscribedTenantCredentials();
+	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
+	if (!creds[tenant]) throw createError({
+		message: `No subscribed tenant credentials found for tenant '${tenant}'`,
+		status: 500
+	});
+	const client = new Client(new BasicAuth(creds[tenant]), process.env.C8Y_BASEURL);
+	client.core.tenant = tenant;
+	return client;
+}
+//#endregion
+export { buildPublicRequestUrl as n, tryGetUserTenantDomainFast as r, useDeployedTenantClient as t };

package/dist/{index-ByDSMEvU.d.mts → index-vu4xaFkz.d.mts}

@@ -383,6 +383,30 @@ interface C8yCacheOptions {
   tenantOptions?: C8YTenantOptionKeysCacheConfig;
 }
 //#endregion
+//#region src/types/docker.d.ts
+interface C8yDockerOptions {
+  /**
+   * Base image for the generated Dockerfile.
+   *
+   * Use this when the default slim image is missing something the service
+   * needs at runtime (e.g. CA certificates, native runtime libraries).
+   * @default 'node:24-slim'
+   */
+  baseImage?: string;
+  /**
+   * Raw Dockerfile instructions inserted after `WORKDIR` and before the build
+   * output is copied, one instruction per entry.
+   *
+   * Placing them before the `COPY` keeps their layers cached across rebuilds.
+   * `ENV`, `EXPOSE 80` and the `CMD` entrypoint stay under module control and
+   * cannot be overridden — they are the Cumulocity microservice contract.
+   *
+   * @example ['RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*']
+   * @default []
+   */
+  extraInstructions?: string[];
+}
+//#endregion
 //#region src/types/roles.d.ts
 interface C8YRoles$1 {}
 //#endregion
@@ -415,12 +439,38 @@ interface C8yDevOptions {
    */
   injectUser?: boolean;
 }
+interface C8yOpenAPIOptions {
+  /**
+   * Strip internal routes from the served OpenAPI document.
+   * Removes every route starting with `/_` (generated probes, `/_c8y_nitro/**`
+   * and the OpenAPI/Scalar/Swagger routes themselves) as well as user-defined
+   * probe `httpGet` paths.
+   * @default true
+   */
+  excludeInternalRoutes?: boolean;
+  /**
+   * Additional route prefixes to strip from the served OpenAPI document.
+   * Entries are matched as path prefixes (e.g. `/internal` also removes `/internal/status`).
+   * @default []
+   */
+  excludeRoutes?: string[];
+}
 interface C8yNitroModuleOptions {
   dev?: C8yDevOptions;
   manifest?: C8YManifestOptions;
   apiClient?: C8YAPIClientOptions;
   zip?: C8YZipOptions;
+  /**
+   * Controls the Dockerfile generated for the microservice image
+   * (base image, extra instructions).
+   */
+  docker?: C8yDockerOptions;
   cache?: C8yCacheOptions;
+  /**
+   * Controls how the OpenAPI document served by Nitro (`experimental.openAPI`)
+   * is transformed for Cumulocity microservices.
+   */
+  openapi?: C8yOpenAPIOptions;
   /**
    * Adds a debug route for invalidating already-created tenant option caches.
    * Exposes `GET /_c8y_nitro/invalidate-tenant-options`.
@@ -444,4 +494,4 @@ interface C8yNitroModuleOptions {
   skipBootstrap?: boolean;
 }
 //#endregion
-export { C8YTenantOptionKeysCacheConfig$1 as a, C8YZipOptions as c, C8YAPIClientOptions as d, C8YTenantOptionKey$1 as i, C8YManifest as l, C8yNitroModuleOptions as n, C8YRoles$1 as o, C8YSettingsCategory$1 as r, C8yCacheOptions as s, C8yDevOptions as t, C8YManifestOptions as u };
+export { C8YTenantOptionKey$1 as a, C8yDockerOptions as c, C8YManifest as d, C8YManifestOptions as f, C8YSettingsCategory$1 as i, C8yCacheOptions as l, C8yNitroModuleOptions as n, C8YTenantOptionKeysCacheConfig$1 as o, C8YAPIClientOptions as p, C8yOpenAPIOptions as r, C8YRoles$1 as s, C8yDevOptions as t, C8YZipOptions as u };