timonel 3.1.1 → 3.1.2

package/dist/lib/utils/valuesRef.js

@@ -1,14 +1,27 @@
+/**
+ * Type-safe Helm values reference system.
+ *
+ * ValuesRef exposes the shape of the caller-provided values interface while
+ * preserving a runtime proxy that renders Helm expressions.
+ */
 import { createHelmExpression } from './helmControlStructures.js';
 const HELM_VALUE_SYMBOL = Symbol('HelmValue');
+/** Escape a JavaScript string as a Helm double-quoted string literal. */
+function helmStringLiteral(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Convert a typed Helm reference or scalar into a Helm expression argument. */
 function serializeValue(value) {
-    if (typeof value === 'object' && value !== null && HELM_VALUE_SYMBOL in value) {
+    if (isHelmValue(value)) {
         return value.__path;
     }
-    if (typeof value === 'string') {
-        return `"${value}"`;
-    }
-    return String(value);
+    return typeof value === 'string' ? helmStringLiteral(value) : String(value);
 }
+/** Append a property segment while preserving scoped `.` semantics. */
+function appendPropertyPath(path, property) {
+    return path === '.' ? `.${property}` : `${path}.${property}`;
+}
+/** Create a validated, composable Helm condition marker. */
 function createCondition(condition) {
     if (!condition || typeof condition !== 'string') {
         throw new Error('Condition must be a non-empty string');
@@ -16,258 +29,243 @@ function createCondition(condition) {
     return {
         [HELM_VALUE_SYMBOL]: true,
         __condition: condition,
+        /** Negate the current condition. */
         not() {
             return createCondition(`not (${this.__condition})`);
         },
+        /** Combine the current condition with another using Helm `and`. */
         and(other) {
             if (!other || typeof other.__condition !== 'string') {
                 throw new Error('Invalid HelmCondition provided to and()');
             }
             return createCondition(`and (${this.__condition}) (${other.__condition})`);
         },
+        /** Combine the current condition with another using Helm `or`. */
         or(other) {
             if (!other || typeof other.__condition !== 'string') {
                 throw new Error('Invalid HelmCondition provided to or()');
             }
             return createCondition(`or (${this.__condition}) (${other.__condition})`);
         },
+        /** Return the raw condition body. */
         toString() {
             return this.__condition;
         },
     };
 }
-function createValueProxy(path) {
+/**
+ * Creates the runtime proxy used by ValuesRef and by serializer callback scopes.
+ * This function is intentionally not re-exported from the package root.
+ */
+export function createHelmValueProxy(path) {
     const baseObject = Object.create(null);
-    baseObject.__helmExpression = true;
-    baseObject.value = `{{ ${path} }}`;
     const handler = {
-        ownKeys() {
-            return ['__helmExpression', 'value'];
-        },
-        getOwnPropertyDescriptor(target, prop) {
-            if (prop === '__helmExpression') {
-                return { value: true, writable: false, enumerable: true, configurable: true };
-            }
-            if (prop === 'value') {
-                return { value: `{{ ${path} }}`, writable: false, enumerable: true, configurable: true };
-            }
-            return undefined;
-        },
-        has(target, prop) {
-            if (prop === HELM_VALUE_SYMBOL)
-                return true;
-            if (prop === '__helmExpression')
-                return true;
-            if (prop === 'value')
-                return true;
-            return false;
+        /** Expose only Timonel's internal marker through the Proxy `in` trap. */
+        has(_target, prop) {
+            return prop === HELM_VALUE_SYMBOL;
         },
-        get(target, prop) {
+        /** Resolve helper methods, runtime markers, and nested typed property proxies. */
+        get(_target, prop) {
             if (prop === HELM_VALUE_SYMBOL)
                 return true;
             if (prop === '__path')
                 return path;
             if (prop === '__type')
                 return undefined;
-            if (prop === '__helmExpression')
-                return true;
-            if (prop === 'value')
-                return `{{ ${path} }}`;
+            if (prop === Symbol.toPrimitive)
+                return () => path;
             if (prop === 'toJSON') {
-                return () => ({ __helmExpression: true, value: `{{ ${path} }}` });
+                return () => `{{ ${path} }}`;
             }
-            if (typeof prop === 'string') {
-                switch (prop) {
-                    case 'eq':
-                        return (value) => createCondition(`eq ${path} ${serializeValue(value)}`);
-                    case 'ne':
-                        return (value) => createCondition(`ne ${path} ${serializeValue(value)}`);
-                    case 'gt':
-                        return (value) => createCondition(`gt ${path} ${serializeValue(value)}`);
-                    case 'ge':
-                        return (value) => createCondition(`ge ${path} ${serializeValue(value)}`);
-                    case 'lt':
-                        return (value) => createCondition(`lt ${path} ${serializeValue(value)}`);
-                    case 'le':
-                        return (value) => createCondition(`le ${path} ${serializeValue(value)}`);
-                    case 'not':
-                        return () => createCondition(`not ${path}`);
-                    case 'and':
-                        return (other) => createCondition(`and ${path} (${other.__condition})`);
-                    case 'or':
-                        return (other) => createCondition(`or ${path} (${other.__condition})`);
-                    case 'default':
-                        return (defaultValue) => createValueProxy(`${path} | default ${serializeValue(defaultValue)}`);
-                    case 'quote':
-                        return () => createValueProxy(`(${path} | quote)`);
-                    case 'upper':
-                        return () => createValueProxy(`(${path} | upper)`);
-                    case 'lower':
-                        return () => createValueProxy(`(${path} | lower)`);
-                    case 'title':
-                        return () => createValueProxy(`(${path} | title)`);
-                    case 'trim':
-                        return () => createValueProxy(`(${path} | trim)`);
-                    case 'trimPrefix':
-                        return (prefix) => createValueProxy(`(${path} | trimPrefix "${prefix}")`);
-                    case 'trimSuffix':
-                        return (suffix) => createValueProxy(`(${path} | trimSuffix "${suffix}")`);
-                    case 'replace':
-                        return (old, newStr) => createValueProxy(`(${path} | replace "${old}" "${newStr}")`);
-                    case 'contains':
-                        return (substr) => createCondition(`contains "${substr}" ${path}`);
-                    case 'hasPrefix':
-                        return (prefix) => createCondition(`hasPrefix ${path} "${prefix}"`);
-                    case 'hasSuffix':
-                        return (suffix) => createCondition(`hasSuffix ${path} "${suffix}"`);
-                    case 'trunc':
-                        return (length) => createValueProxy(`(${path} | trunc ${length})`);
-                    case 'kindIs':
-                        return (kind) => createCondition(`kindIs "${kind}" ${path}`);
-                    case 'hasKey':
-                        return (key) => createCondition(`hasKey ${path} "${key}"`);
-                    case 'toYaml':
-                        return () => createValueProxy(`${path} | toYaml`);
-                    case 'toJson':
-                        return () => createValueProxy(`${path} | toJson`);
-                    case 'nindent':
-                        return (spaces) => createValueProxy(`${path} | nindent ${spaces}`);
-                    case 'indent':
-                        return (spaces) => createValueProxy(`${path} | indent ${spaces}`);
-                    case 'toExpression':
-                        return () => createHelmExpression(`{{ ${path} }}`);
-                    case 'if':
-                        return (condition, thenValue) => {
-                            let helmCondition;
-                            if (isHelmCondition(condition)) {
-                                helmCondition = condition;
-                            }
-                            else if (isHelmValue(condition)) {
-                                helmCondition = createCondition(condition.__path);
-                            }
-                            else {
-                                throw new Error('v.if() requires a HelmCondition or HelmValue as the first argument');
-                            }
-                            return {
-                                __helmFieldConditional: true,
-                                condition: helmCondition,
-                                thenValue,
-                            };
-                        };
-                    case 'ifElse':
-                        return (condition, thenValue, elseValue) => {
-                            const condStr = condition.__condition;
-                            return createValueProxy(`(ternary ${serializeValue(thenValue)} ${serializeValue(elseValue)} (${condStr}))`);
-                        };
-                    case 'range':
-                        return (callback) => ({
-                            __helmRange: true,
-                            source: createValueProxy(path),
-                            callback,
-                        });
-                    case 'with':
-                        return (callback) => {
-                            const ctxProxy = { __path: '.', [HELM_VALUE_SYMBOL]: true };
-                            const content = callback(ctxProxy);
-                            let contentStr;
-                            if (typeof content === 'object' &&
-                                content !== null &&
-                                '__helmExpression' in content) {
-                                const helmExpr = content;
-                                contentStr = helmExpr.value;
-                            }
-                            else {
-                                contentStr = String(content);
-                            }
-                            const marker = `__FIELD_WITH_MARKER__:${path}:${contentStr}`;
-                            return createHelmExpression(marker);
+            if (typeof prop !== 'string')
+                return undefined;
+            switch (prop) {
+                case 'at':
+                    return (key) => createHelmValueProxy(appendPropertyPath(path, key));
+                case 'eq':
+                    return (value) => createCondition(`eq ${path} ${serializeValue(value)}`);
+                case 'ne':
+                    return (value) => createCondition(`ne ${path} ${serializeValue(value)}`);
+                case 'gt':
+                    return (value) => createCondition(`gt ${path} ${serializeValue(value)}`);
+                case 'ge':
+                    return (value) => createCondition(`ge ${path} ${serializeValue(value)}`);
+                case 'lt':
+                    return (value) => createCondition(`lt ${path} ${serializeValue(value)}`);
+                case 'le':
+                    return (value) => createCondition(`le ${path} ${serializeValue(value)}`);
+                case 'not':
+                    return () => createCondition(`not ${path}`);
+                case 'and':
+                    return (other) => createCondition(`and ${path} (${other.__condition})`);
+                case 'or':
+                    return (other) => createCondition(`or ${path} (${other.__condition})`);
+                case 'default':
+                    return (defaultValue) => createHelmValueProxy(`${path} | default ${serializeValue(defaultValue)}`);
+                case 'quote':
+                    return () => createHelmValueProxy(`(${path} | quote)`);
+                case 'upper':
+                    return () => createHelmValueProxy(`(${path} | upper)`);
+                case 'lower':
+                    return () => createHelmValueProxy(`(${path} | lower)`);
+                case 'title':
+                    return () => createHelmValueProxy(`(${path} | title)`);
+                case 'trim':
+                    return () => createHelmValueProxy(`(${path} | trim)`);
+                case 'trimPrefix':
+                    return (prefix) => createHelmValueProxy(`(${path} | trimPrefix ${helmStringLiteral(prefix)})`);
+                case 'trimSuffix':
+                    return (suffix) => createHelmValueProxy(`(${path} | trimSuffix ${helmStringLiteral(suffix)})`);
+                case 'replace':
+                    return (old, newStr) => createHelmValueProxy(`(${path} | replace ${helmStringLiteral(old)} ${helmStringLiteral(newStr)})`);
+                case 'contains':
+                    return (substr) => createCondition(`contains ${helmStringLiteral(substr)} ${path}`);
+                case 'hasPrefix':
+                    return (prefix) => createCondition(`hasPrefix ${helmStringLiteral(prefix)} ${path}`);
+                case 'hasSuffix':
+                    return (suffix) => createCondition(`hasSuffix ${helmStringLiteral(suffix)} ${path}`);
+                case 'trunc':
+                    return (length) => createHelmValueProxy(`(${path} | trunc ${length})`);
+                case 'kindIs':
+                    return (kind) => createCondition(`kindIs ${helmStringLiteral(kind)} ${path}`);
+                case 'hasKey':
+                    return (key) => createCondition(`hasKey ${path} ${helmStringLiteral(key)}`);
+                case 'toYaml':
+                    return () => createHelmValueProxy(`${path} | toYaml`);
+                case 'toJson':
+                    return () => createHelmValueProxy(`${path} | toJson`);
+                case 'nindent':
+                    return (spaces) => createHelmValueProxy(`${path} | nindent ${spaces}`);
+                case 'indent':
+                    return (spaces) => createHelmValueProxy(`${path} | indent ${spaces}`);
+                case 'toExpression':
+                    return () => createHelmExpression(`{{ ${path} }}`);
+                case 'if':
+                    return (condition, thenValue) => {
+                        const helmCondition = isHelmCondition(condition)
+                            ? condition
+                            : isHelmValue(condition)
+                                ? createCondition(condition.__path)
+                                : undefined;
+                        if (!helmCondition) {
+                            throw new Error('v.if() requires a HelmCondition or HelmValue as the first argument');
+                        }
+                        return {
+                            __helmFieldConditional: true,
+                            condition: helmCondition,
+                            thenValue,
                         };
-                    case 'toString':
-                        return () => `{{ ${path} }}`;
-                    case 'valueOf':
-                        return () => path;
-                    default:
-                        return createValueProxy(`${path}.${prop}`);
-                }
+                    };
+                case 'ifElse':
+                    return (condition, thenValue, elseValue) => createHelmValueProxy(`(ternary ${serializeValue(thenValue)} ${serializeValue(elseValue)} (${condition.__condition}))`);
+                case 'range':
+                    return (callback) => ({
+                        __helmRange: true,
+                        source: createHelmValueProxy(path),
+                        callback,
+                    });
+                case 'with':
+                    return (callback) => ({
+                        __helmWith: true,
+                        source: createHelmValueProxy(path),
+                        callback,
+                    });
+                case 'toString':
+                    return () => `{{ ${path} }}`;
+                case 'valueOf':
+                    return () => path;
+                default:
+                    return createHelmValueProxy(appendPropertyPath(path, prop));
             }
-            return undefined;
         },
     };
     return new Proxy(baseObject, handler);
 }
+/** Creates a type-safe reference tree rooted at `.Values`. */
 export function valuesRef() {
-    const values = createValueProxy('.Values');
+    const values = createHelmValueProxy('.Values');
     const helpers = {
+        /** Implement the root Helm `include` helper. */
         include(templateName, context = '.') {
             const ctx = context === '.' ? '.' : context.__path;
-            return createValueProxy(`(include "${templateName}" ${ctx})`);
+            return createHelmValueProxy(`(include ${helmStringLiteral(templateName)} ${ctx})`);
         },
+        /** Implement the root Helm `printf` helper. */
         printf(format, ...args) {
-            const argsStr = args
-                .map((arg) => serializeValue(arg))
-                .join(' ');
-            return createValueProxy(`(printf "${format}" ${argsStr})`);
+            const argsStr = args.map((arg) => serializeValue(arg)).join(' ');
+            const suffix = argsStr ? ` ${argsStr}` : '';
+            return createHelmValueProxy(`(printf ${helmStringLiteral(format)}${suffix})`);
         },
         release: {
-            name: createValueProxy('.Release.Name'),
-            namespace: createValueProxy('.Release.Namespace'),
-            service: createValueProxy('.Release.Service'),
-            isUpgrade: createValueProxy('.Release.IsUpgrade'),
-            isInstall: createValueProxy('.Release.IsInstall'),
-            revision: createValueProxy('.Release.Revision'),
+            name: createHelmValueProxy('.Release.Name'),
+            namespace: createHelmValueProxy('.Release.Namespace'),
+            service: createHelmValueProxy('.Release.Service'),
+            isUpgrade: createHelmValueProxy('.Release.IsUpgrade'),
+            isInstall: createHelmValueProxy('.Release.IsInstall'),
+            revision: createHelmValueProxy('.Release.Revision'),
         },
         chart: {
-            name: createValueProxy('.Chart.Name'),
-            version: createValueProxy('.Chart.Version'),
-            appVersion: createValueProxy('.Chart.AppVersion'),
-            type: createValueProxy('.Chart.Type'),
+            name: createHelmValueProxy('.Chart.Name'),
+            version: createHelmValueProxy('.Chart.Version'),
+            appVersion: createHelmValueProxy('.Chart.AppVersion'),
+            type: createHelmValueProxy('.Chart.Type'),
         },
         capabilities: {
             kubeVersion: {
-                version: createValueProxy('.Capabilities.KubeVersion.Version'),
-                major: createValueProxy('.Capabilities.KubeVersion.Major'),
-                minor: createValueProxy('.Capabilities.KubeVersion.Minor'),
+                version: createHelmValueProxy('.Capabilities.KubeVersion.Version'),
+                major: createHelmValueProxy('.Capabilities.KubeVersion.Major'),
+                minor: createHelmValueProxy('.Capabilities.KubeVersion.Minor'),
             },
             apiVersions: {
+                /** Test `.Capabilities.APIVersions` for an advertised API. */
                 has(apiVersion) {
-                    return createCondition(`.Capabilities.APIVersions.Has "${apiVersion}"`);
+                    return createCondition(`.Capabilities.APIVersions.Has ${helmStringLiteral(apiVersion)}`);
                 },
             },
         },
+        /** Build a condition from a caller-supplied Helm condition body. */
         rawCondition(condition) {
             return createCondition(condition);
         },
     };
     return new Proxy(values, {
+        /** Route reserved root helper names before delegating to the values proxy. */
         get(target, prop) {
-            if (prop in helpers) {
-                return helpers[prop];
+            if (Object.prototype.hasOwnProperty.call(helpers, prop)) {
+                return Reflect.get(helpers, prop);
             }
-            return target[prop];
+            return Reflect.get(target, prop);
         },
     });
 }
+/** Check if a value is a Helm value proxy. */
 export function isHelmValue(value) {
     return typeof value === 'object' && value !== null && HELM_VALUE_SYMBOL in value;
 }
+/** Check if a value is a Helm condition. */
 export function isHelmCondition(value) {
     return (typeof value === 'object' &&
         value !== null &&
         HELM_VALUE_SYMBOL in value &&
         '__condition' in value);
 }
+/** Check if a value is a field-level conditional. */
 export function isHelmFieldConditional(value) {
     return typeof value === 'object' && value !== null && '__helmFieldConditional' in value;
 }
+/** Check if a value is a range block. */
 export function isHelmRange(value) {
     return typeof value === 'object' && value !== null && '__helmRange' in value;
 }
+/** Check if a value is a with block. */
 export function isHelmWith(value) {
     return typeof value === 'object' && value !== null && '__helmWith' in value;
 }
+/** Serialize a Helm value reference to template syntax. */
 export function serializeHelmValue(value) {
     return `{{ ${value.__path} }}`;
 }
+/** Serialize a Helm condition body. */
 export function serializeHelmCondition(condition) {
     return condition.__condition;
 }

package/dist/lib/validation/inputValidator.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Input validation utilities for the Policy Engine
+ * Provides comprehensive validation for all user inputs to prevent
+ * injection attacks and malformed data processing
+ */
 import type { PolicyConfig, PolicyContext, PolicyRule, PluginConfig } from '../../types/index.js';
+/**
+ * Validation configuration options
+ */
 export interface ValidationOptions {
     maxStringLength?: number;
     maxArrayLength?: number;
@@ -6,20 +14,57 @@ export interface ValidationOptions {
     allowedProtocols?: string[];
     sanitizeStrings?: boolean;
 }
+/**
+ * Input validator class for policy engine inputs
+ */
 export declare class InputValidator {
     private options;
     constructor(options?: ValidationOptions);
+    /**
+     * Validates a PolicyConfig object
+     */
     validatePolicyConfig(config: unknown): PolicyConfig;
+    /**
+     * Validates a PolicyRule object
+     */
     validatePolicyRule(rule: unknown): PolicyRule;
+    /**
+     * Validates a PolicyContext object
+     */
     validatePolicyContext(context: unknown): PolicyContext;
+    /**
+     * Validates a PluginConfig object
+     */
     validatePluginConfig(config: unknown): PluginConfig;
+    /**
+     * Validates string length against maximum allowed
+     */
     private validateStringLength;
+    /**
+     * Validates array length against maximum allowed
+     */
     private validateArrayLength;
+    /**
+     * Validates object depth to prevent deeply nested objects
+     */
     private validateObjectDepth;
+    /**
+     * Sanitizes a string by removing potentially dangerous characters
+     * Focuses on policy configuration validation, not HTML sanitization
+     */
     private sanitizeString;
+    /**
+     * Sanitizes an object recursively
+     */
     private sanitizeObject;
 }
+/**
+ * Default input validator instance
+ */
 export declare const defaultValidator: InputValidator;
+/**
+ * Convenience functions for common validation scenarios
+ */
 export declare const validatePolicyConfig: (config: unknown) => PolicyConfig;
 export declare const validatePolicyRule: (rule: unknown) => PolicyRule;
 export declare const validatePolicyContext: (context: unknown) => PolicyContext;