@ninenity/neutrun 1.2.0 → 1.9.2

package/dist/Shared/ExpressApi.js

@@ -10,6 +10,7 @@ const node_crypto_1 = require("node:crypto");
 const ConsoleLog_1 = require("./ConsoleLog");
 const ProcessManager_1 = __importDefault(require("./ProcessManager"));
 const TelemetryService_1 = require("./TelemetryService");
+const Observability_1 = __importDefault(require("./Observability"));
 class ApiRequestError extends Error {
     status;
     data;
@@ -25,13 +26,18 @@ class ApiRequestError extends Error {
 exports.ApiRequestError = ApiRequestError;
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 3000;
-const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30 * 1000;
 const DEFAULT_RATE_LIMIT_WINDOW_MS = 60 * 1000;
 const DEFAULT_RATE_LIMIT_MAX = 60;
 const MAX_RATE_LIMIT_ENTRIES = 10_000;
 const SERVER_CLOSE_TIMEOUT_MS = 5_000;
 const MAX_INTERNAL_RESPONSE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_HEADER_BYTES = 16 * 1024;
+const DEFAULT_MAX_QUERY_PARAMETERS = 100;
+const DEFAULT_MAX_JSON_DEPTH = 16;
+const DEFAULT_MAX_JSON_KEYS = 1_000;
+const REQUEST_ID_PATTERN = /^[a-zA-Z0-9._:-]{8,100}$/;
 class ExpressApiService {
     app;
     settings = normalizeSettings(undefined);
@@ -59,6 +65,11 @@ class ExpressApiService {
         this.app.stop = () => this.stop();
         this.app.fetch = (path, options) => this.fetch(path, options);
         this.app.fetchJson = (path, options) => this.fetchJson(path, options);
+        this.app.protect = (options) => this.protectionMiddleware(options);
+        this.app.validate = (options) => this.validationMiddleware(options);
+        this.app.getIdentity = (response) => response.locals.neutrunIdentity;
+        this.app.getStatus = () => this.getStatus();
+        TelemetryService_1.Telemetry.setApiStatusProvider(() => this.getTelemetryStatus());
         Object.defineProperties(this.app, {
             isRunning: {
                 enumerable: true,
@@ -95,6 +106,19 @@ class ExpressApiService {
             return;
         this.installBuiltInMiddleware();
     }
+    getStatus() {
+        return {
+            configured: this.configured,
+            enabled: this.settings.enabled,
+            running: this.server !== null,
+            suspended: this.resourcesSuspended,
+            hibernating: this.isHibernating,
+            lifecycle: this.settings.lifecycle.mode,
+            host: this.settings.host,
+            port: this.settings.port,
+            url: this.url
+        };
+    }
     finalize() {
         if (this.finalized)
             return;
@@ -131,7 +155,9 @@ class ExpressApiService {
         validateSettings(this.settings);
         this.finalize();
         this.startPromise = new Promise((resolve, reject) => {
-            const server = (0, node_http_1.createServer)(this.app);
+            const server = (0, node_http_1.createServer)({
+                maxHeaderSize: clampInteger(this.settings.security.maxHeaderBytes, 8 * 1024, 64 * 1024, DEFAULT_MAX_HEADER_BYTES)
+            }, this.app);
             const requestTimeout = this.settings.security.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
             server.requestTimeout = requestTimeout;
             server.headersTimeout = Math.max(requestTimeout + 1_000, 5_000);
@@ -197,7 +223,7 @@ class ExpressApiService {
         await this.ensureStarted();
         const url = this.resolveUrl(path);
         const headers = new Headers(options.headers);
-        const token = this.resolveToken();
+        const token = this.resolveCredentials()[0]?.token ?? '';
         const authentication = this.settings.security.authentication;
         if (token && authentication !== 'none' && !headers.has('authorization') && !headers.has('x-api-key')) {
             if (authentication === 'api-key')
@@ -205,6 +231,9 @@ class ExpressApiService {
             else
                 headers.set('authorization', `Bearer ${token}`);
         }
+        if (!headers.has('x-request-id')) {
+            headers.set('x-request-id', Observability_1.default.getCorrelationId() ?? (0, node_crypto_1.randomUUID)());
+        }
         const body = serializeBody(options.body, headers);
         const { query, ...init } = options;
         const requestInit = {
@@ -225,9 +254,11 @@ class ExpressApiService {
     }
     installBuiltInMiddleware() {
         this.middlewareInstalled = true;
+        this.app.use(this.requestContextMiddleware());
         this.app.use(this.securityHeaders());
         this.app.use(this.corsMiddleware());
         this.app.use(this.requestTrackingMiddleware());
+        this.app.use(this.requestShapeLimitsMiddleware());
         this.app.use(this.requestTimeoutMiddleware());
         this.app.use(this.rateLimitMiddleware());
         this.app.use(this.authenticationMiddleware());
@@ -237,6 +268,16 @@ class ExpressApiService {
             extended: true,
             limit: this.settings.security.bodyLimit ?? '1mb'
         }));
+        this.app.use(this.jsonComplexityMiddleware());
+    }
+    requestContextMiddleware() {
+        return (req, res, next) => {
+            const incoming = req.get('x-request-id')?.trim() || '';
+            const requestId = REQUEST_ID_PATTERN.test(incoming) ? incoming : (0, node_crypto_1.randomUUID)();
+            res.locals.neutrunRequestId = requestId;
+            res.setHeader('X-Request-Id', requestId);
+            Observability_1.default.run({ correlationId: requestId, requestId, source: 'express-api' }, () => next());
+        };
     }
     securityHeaders() {
         return (_req, res, next) => {
@@ -244,6 +285,9 @@ class ExpressApiService {
             res.setHeader('X-Frame-Options', 'DENY');
             res.setHeader('Referrer-Policy', 'no-referrer');
             res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+            res.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'; base-uri 'none'");
+            res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()');
+            res.setHeader('Cache-Control', 'no-store');
             next();
         };
     }
@@ -260,8 +304,8 @@ class ExpressApiService {
                     : undefined;
             if (allowed) {
                 res.setHeader('Access-Control-Allow-Origin', allowed);
-                res.setHeader('Vary', 'Origin');
-                res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-API-Key');
+                appendVaryHeader(res, 'Origin');
+                res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-API-Key, X-Request-Id');
                 res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
             }
             if (req.method === 'OPTIONS')
@@ -271,6 +315,7 @@ class ExpressApiService {
     }
     requestTrackingMiddleware() {
         return (req, res, next) => {
+            const startedAt = performance.now();
             this.lastActivityAt = Date.now();
             this.activeRequests += 1;
             let completed = false;
@@ -281,13 +326,49 @@ class ExpressApiService {
                 this.activeRequests = Math.max(0, this.activeRequests - 1);
                 this.lastActivityAt = Date.now();
                 this.scheduleIdleCheck();
-                this.recordRequest(req, res, res.statusCode);
+                this.recordRequest(req, res, res.statusCode, performance.now() - startedAt, !res.writableEnded);
             };
             res.once('finish', complete);
             res.once('close', complete);
             next();
         };
     }
+    requestShapeLimitsMiddleware() {
+        return (req, res, next) => {
+            const maximum = clampInteger(this.settings.security.maxQueryParameters, 1, 1_000, DEFAULT_MAX_QUERY_PARAMETERS);
+            if (countObjectKeys(req.query, maximum + 1) > maximum) {
+                this.emitAudit(req, res, {
+                    type: 'validation',
+                    outcome: 'denied',
+                    status: 400,
+                    reason: 'query_limit'
+                });
+                return res.status(400).json({ success: false, error: 'Too many query parameters' });
+            }
+            next();
+        };
+    }
+    jsonComplexityMiddleware() {
+        return (req, res, next) => {
+            if (req.body === undefined || req.body === null || typeof req.body !== 'object')
+                return next();
+            const maxDepth = clampInteger(this.settings.security.maxJsonDepth, 1, 100, DEFAULT_MAX_JSON_DEPTH);
+            const maxKeys = clampInteger(this.settings.security.maxJsonKeys, 1, 100_000, DEFAULT_MAX_JSON_KEYS);
+            const complexity = inspectObjectComplexity(req.body, maxDepth, maxKeys);
+            if (complexity.valid)
+                return next();
+            this.emitAudit(req, res, {
+                type: 'validation',
+                outcome: 'denied',
+                status: 400,
+                reason: complexity.reason
+            });
+            return res.status(400).json({
+                success: false,
+                error: 'Request body is too complex'
+            });
+        };
+    }
     requestTimeoutMiddleware() {
         return (_req, res, next) => {
             const timeoutMs = this.settings.security.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
@@ -320,11 +401,21 @@ class ExpressApiService {
             const current = this.rateLimitEntries.get(key);
             if (!current || now - current.startedAt >= windowMs) {
                 this.rateLimitEntries.set(key, { startedAt: now, count: 1 });
+                setRateLimitHeaders(res, max, max - 1, windowMs);
                 return next();
             }
-            current.count += 1;
+            current.count = Math.min(Number.MAX_SAFE_INTEGER, current.count + 1);
+            const remaining = Math.max(0, max - current.count);
+            const resetMs = Math.max(0, windowMs - (now - current.startedAt));
+            setRateLimitHeaders(res, max, remaining, resetMs);
             if (current.count > max) {
-                res.setHeader('Retry-After', Math.ceil((windowMs - (now - current.startedAt)) / 1_000));
+                res.setHeader('Retry-After', Math.ceil(resetMs / 1_000));
+                Observability_1.default.increment('neutrun_api_rate_limit_total');
+                this.emitAudit(req, res, {
+                    type: 'rate-limit',
+                    outcome: 'denied',
+                    status: 429
+                });
                 return res.status(429).json({
                     success: false,
                     error: 'Too Many Requests'
@@ -336,27 +427,118 @@ class ExpressApiService {
     authenticationMiddleware() {
         return (req, res, next) => {
             const authentication = this.settings.security.authentication;
-            const token = this.resolveToken();
-            if (authentication === 'none' || !token || isPublicPath(req.path, this.settings.security.publicPaths)) {
+            if (authentication === 'none') {
+                res.locals.neutrunIdentity = anonymousIdentity();
+                return next();
+            }
+            if (isPublicPath(req.path, this.settings.security.publicPaths)) {
+                res.locals.neutrunIdentity = anonymousIdentity();
                 return next();
             }
             const received = authentication === 'api-key'
                 ? req.get('x-api-key')
                 : extractBearerToken(req.get('authorization'));
-            if (!received || !timingSafeEqual(received, token)) {
+            const credential = received
+                ? this.resolveCredentials().find((entry) => timingSafeEqual(received, entry.token))
+                : undefined;
+            if (!credential) {
+                Observability_1.default.increment('neutrun_api_authentication_total', 1, { outcome: 'denied' });
+                this.emitAudit(req, res, {
+                    type: 'authentication',
+                    outcome: 'denied',
+                    status: 401,
+                    reason: received ? 'invalid_credential' : 'missing_credential'
+                });
                 return res.status(401).json({
                     success: false,
                     error: 'Unauthorized'
                 });
             }
+            const identity = {
+                authentication,
+                credentialId: credential.id,
+                roles: credential.roles,
+                scopes: credential.scopes
+            };
+            res.locals.neutrunIdentity = identity;
+            Observability_1.default.increment('neutrun_api_authentication_total', 1, { outcome: 'allowed' });
+            this.emitAudit(req, res, {
+                type: 'authentication',
+                outcome: 'allowed',
+                credentialId: credential.id
+            });
             next();
         };
     }
-    resolveToken() {
-        const configured = this.settings.security.token?.trim();
-        if (configured)
-            return configured;
-        return process.env[this.settings.security.tokenEnv]?.trim() || '';
+    protectionMiddleware(options = {}) {
+        return (req, res, next) => {
+            const run = async () => {
+                const identity = res.locals.neutrunIdentity;
+                const roles = new Set(identity?.roles ?? []);
+                const scopes = new Set(identity?.scopes ?? []);
+                const hasRoles = (options.roles ?? []).every((role) => roles.has(role));
+                const hasScopes = (options.scopes ?? []).every((scope) => scopes.has(scope));
+                const policyEligible = Boolean(identity && identity.authentication !== 'none' && hasRoles && hasScopes);
+                const customAllowed = policyEligible && options.authorize
+                    ? await options.authorize(req, identity)
+                    : policyEligible;
+                if (policyEligible && identity && customAllowed) {
+                    this.emitAudit(req, res, {
+                        type: 'authorization',
+                        outcome: 'allowed',
+                        credentialId: identity.credentialId
+                    });
+                    next();
+                    return;
+                }
+                Observability_1.default.increment('neutrun_api_authorization_total', 1, { outcome: 'denied' });
+                this.emitAudit(req, res, {
+                    type: 'authorization',
+                    outcome: 'denied',
+                    status: identity?.authentication === 'none' ? 401 : 403,
+                    credentialId: identity?.credentialId,
+                    reason: 'policy_denied'
+                });
+                res.status(identity?.authentication === 'none' ? 401 : 403).json({
+                    success: false,
+                    error: identity?.authentication === 'none' ? 'Unauthorized' : 'Forbidden'
+                });
+            };
+            void run().catch(next);
+        };
+    }
+    validationMiddleware(options) {
+        return (req, res, next) => {
+            const run = async () => {
+                const checks = [
+                    ['body', options.body, req.body],
+                    ['query', options.query, req.query],
+                    ['params', options.params, req.params]
+                ];
+                for (const [part, validator, value] of checks) {
+                    if (!validator)
+                        continue;
+                    const result = await validator(value, req);
+                    if (result === false || typeof result === 'string') {
+                        const reason = typeof result === 'string' ? result.slice(0, 200) : `Invalid ${part}`;
+                        Observability_1.default.increment('neutrun_api_validation_total', 1, { outcome: 'denied', part });
+                        this.emitAudit(req, res, {
+                            type: 'validation',
+                            outcome: 'denied',
+                            status: 400,
+                            reason: part
+                        });
+                        res.status(400).json({ success: false, error: reason });
+                        return;
+                    }
+                }
+                next();
+            };
+            void run().catch(next);
+        };
+    }
+    resolveCredentials() {
+        return resolveCredentials(this.settings.security);
     }
     scheduleIdleCheck() {
         this.clearIdleTimer();
@@ -431,13 +613,42 @@ class ExpressApiService {
         this.cleanupRegistered = true;
         ProcessManager_1.default.registerCleanupTask(() => this.stop(), 'mini API Express');
     }
-    recordRequest(req, res, status, error = false) {
-        const path = req.path || req.originalUrl || '/';
+    recordRequest(req, res, status, durationMs, error = false) {
+        const path = normalizeTelemetryPath(req.route?.path ?? req.path ?? '/');
         TelemetryService_1.Telemetry.registerCounter('apiRequests');
         TelemetryService_1.Telemetry.registerEvent(`api:${req.method}:${path}`.slice(0, 120), {
-            error: error || status >= 400
+            error: error || status >= 400,
+            durationMs
+        });
+        Observability_1.default.increment('neutrun_api_requests_total', 1, {
+            method: req.method,
+            outcome: status >= 400 || error ? 'error' : 'success',
+            status: `${Math.floor(status / 100)}xx`
+        });
+        Observability_1.default.observe('neutrun_api_request_duration_ms', durationMs, {
+            method: req.method
+        });
+        this.emitAudit(req, res, {
+            type: 'request',
+            outcome: status >= 400 || error ? 'error' : 'success',
+            status,
+            durationMs
+        });
+    }
+    emitAudit(req, res, event) {
+        const audit = this.settings.security.audit;
+        if (!audit)
+            return;
+        const payload = {
+            ...event,
+            at: new Date().toISOString(),
+            requestId: String(res.locals.neutrunRequestId || (0, node_crypto_1.randomUUID)()),
+            method: req.method.slice(0, 16),
+            path: normalizeTelemetryPath(req.route?.path ?? req.path ?? '/')
+        };
+        void Promise.resolve(audit(payload)).catch((error) => {
+            (0, ConsoleLog_1.logWarn)(`Falha no destino de auditoria da mini API: ${error instanceof Error ? error.message : error}`, 'Api');
         });
-        void res;
     }
     resolveUrl(path) {
         const base = this.url;
@@ -464,6 +675,22 @@ class ExpressApiService {
         const port = typeof address === 'object' && address ? address.port : this.settings.port;
         return this.publicUrl(port);
     }
+    get isHibernating() {
+        return Boolean(this.configured &&
+            this.settings.enabled &&
+            this.settings.lifecycle.mode !== 'always' &&
+            (!this.server || this.resourcesSuspended));
+    }
+    getTelemetryStatus() {
+        return {
+            configured: this.configured,
+            enabled: this.settings.enabled,
+            running: this.server !== null,
+            suspended: this.resourcesSuspended,
+            hibernating: this.isHibernating,
+            lifecycle: this.settings.lifecycle.mode
+        };
+    }
     clearIdleTimer() {
         if (!this.idleTimer)
             return;
@@ -511,32 +738,169 @@ function normalizeSettings(options) {
             onWake: lifecycle.onWake ?? serverlessOptions.onWake
         },
         security: {
-            authentication: api.security?.authentication ?? (resolveToken(api.security) || isPublicHost(host) ? 'bearer' : 'none'),
+            authentication: api.security?.authentication ?? (resolveCredentials(api.security).length > 0 || isPublicHost(host) ? 'bearer' : 'none'),
             token: api.security?.token,
             tokenEnv: api.security?.tokenEnv ?? 'NEUTRUN_API_TOKEN',
+            tokens: api.security?.tokens,
+            tokensEnv: api.security?.tokensEnv ?? 'NEUTRUN_API_TOKENS',
+            credentials: api.security?.credentials,
+            allowInsecurePublic: api.security?.allowInsecurePublic,
             publicPaths: api.security?.publicPaths ?? [],
             cors: api.security?.cors,
             bodyLimit: api.security?.bodyLimit,
             rateLimit: api.security?.rateLimit,
             requestTimeoutMs: api.security?.requestTimeoutMs,
-            trustProxy: api.security?.trustProxy
+            trustProxy: api.security?.trustProxy,
+            maxHeaderBytes: api.security?.maxHeaderBytes,
+            maxQueryParameters: api.security?.maxQueryParameters,
+            maxJsonDepth: api.security?.maxJsonDepth,
+            maxJsonKeys: api.security?.maxJsonKeys,
+            audit: api.security?.audit
         }
     };
 }
 function validateSettings(settings) {
-    const hasToken = Boolean(resolveToken(settings.security));
-    if (settings.security.authentication !== 'none' && !hasToken) {
+    const credentials = resolveCredentials(settings.security);
+    if (settings.security.authentication !== 'none' && credentials.length === 0) {
         throw new Error('A mini API autenticada precisa de security.token ou NEUTRUN_API_TOKEN configurado.');
     }
+    if (settings.security.authentication === 'none' &&
+        isPublicHost(settings.host) &&
+        settings.security.allowInsecurePublic !== true) {
+        throw new Error('A mini API pública não pode desativar autenticação sem security.allowInsecurePublic=true.');
+    }
+    if (settings.security.cors === '*' &&
+        settings.security.authentication !== 'none') {
+        throw new Error('A mini API autenticada exige uma lista explícita de origens CORS.');
+    }
+    if (isPublicHost(settings.host) &&
+        credentials.some((credential) => Buffer.byteLength(credential.token, 'utf8') < 16)) {
+        throw new Error('Credenciais da mini API precisam ter pelo menos 16 bytes.');
+    }
 }
 function isPublicHost(host) {
     return !['127.0.0.1', 'localhost', '::1'].includes(host);
 }
-function resolveToken(security) {
-    const token = security?.token?.trim();
-    if (token)
-        return token;
-    return process.env[security?.tokenEnv ?? 'NEUTRUN_API_TOKEN']?.trim() || '';
+function resolveCredentials(security) {
+    const values = [];
+    for (const credential of security?.credentials ?? [])
+        values.push(credential);
+    for (const token of security?.tokens ?? [])
+        values.push({ token });
+    const tokensEnvironment = process.env[security?.tokensEnv ?? 'NEUTRUN_API_TOKENS'];
+    for (const token of tokensEnvironment?.split(/[\r\n,]+/) ?? [])
+        values.push({ token });
+    const directToken = security?.token?.trim();
+    if (directToken)
+        values.push({ token: directToken });
+    const environmentToken = process.env[security?.tokenEnv ?? 'NEUTRUN_API_TOKEN']?.trim();
+    if (environmentToken)
+        values.push({ token: environmentToken });
+    const seen = new Set();
+    const output = [];
+    for (const value of values) {
+        const token = value.token?.trim();
+        if (!token || seen.has(token))
+            continue;
+        seen.add(token);
+        output.push({
+            token,
+            id: sanitizeCredentialId(value.id) ?? createCredentialId(token),
+            roles: sanitizePolicyValues(value.roles),
+            scopes: sanitizePolicyValues(value.scopes)
+        });
+    }
+    return output;
+}
+function anonymousIdentity() {
+    return { authentication: 'none', roles: [], scopes: [] };
+}
+function sanitizeCredentialId(value) {
+    const normalized = value?.trim();
+    if (!normalized)
+        return undefined;
+    return normalized.replace(/[^a-zA-Z0-9._:-]+/g, '_').slice(0, 100);
+}
+function createCredentialId(token) {
+    return `key_${(0, node_crypto_1.createHash)('sha256').update(token).digest('hex').slice(0, 12)}`;
+}
+function sanitizePolicyValues(values) {
+    return Array.from(new Set((values ?? [])
+        .map((value) => String(value).trim().slice(0, 100))
+        .filter(Boolean)))
+        .slice(0, 100);
+}
+function appendVaryHeader(response, value) {
+    const current = response.getHeader('Vary');
+    const entries = String(current ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    if (!entries.some((entry) => entry.toLowerCase() === value.toLowerCase())) {
+        entries.push(value);
+    }
+    response.setHeader('Vary', entries.join(', '));
+}
+function setRateLimitHeaders(response, limit, remaining, resetMs) {
+    response.setHeader('RateLimit-Limit', limit);
+    response.setHeader('RateLimit-Remaining', remaining);
+    response.setHeader('RateLimit-Reset', Math.ceil(resetMs / 1_000));
+}
+function countObjectKeys(value, stopAfter) {
+    if (!value || typeof value !== 'object')
+        return 0;
+    let count = 0;
+    const stack = [value];
+    const seen = new WeakSet();
+    while (stack.length > 0 && count < stopAfter) {
+        const current = stack.pop();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        for (const entry of Object.values(current)) {
+            count += 1;
+            if (entry && typeof entry === 'object')
+                stack.push(entry);
+            if (count >= stopAfter)
+                break;
+        }
+    }
+    return count;
+}
+function inspectObjectComplexity(value, maxDepth, maxKeys) {
+    const stack = [{ value, depth: 1 }];
+    const seen = new WeakSet();
+    let keys = 0;
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (seen.has(current.value))
+            continue;
+        seen.add(current.value);
+        if (current.depth > maxDepth)
+            return { valid: false, reason: 'json_depth' };
+        for (const entry of Object.values(current.value)) {
+            keys += 1;
+            if (keys > maxKeys)
+                return { valid: false, reason: 'json_keys' };
+            if (entry && typeof entry === 'object') {
+                stack.push({ value: entry, depth: current.depth + 1 });
+            }
+        }
+    }
+    return { valid: true };
+}
+function normalizeTelemetryPath(value) {
+    const raw = String(value || '/').split('?')[0] || '/';
+    return raw
+        .replace(/\b\d{6,}\b/g, ':id')
+        .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, ':id')
+        .slice(0, 120);
+}
+function clampInteger(value, minimum, maximum, fallback) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(minimum, Math.min(maximum, Math.floor(parsed)));
 }
 function normalizePort(value) {
     const parsed = Number(value ?? DEFAULT_PORT);