@aws/cloudformation-validate 1.9.0-beta → 1.10.0

package/index.d.ts

@@ -1,5 +1,6 @@
 import type {
-    DetailedReport,
+    Diagnostic,
+    ValidationReport,
     DiagnosticModel,
     AdditionalSchemaSource,
     ExternalRuleSource,
@@ -8,8 +9,6 @@ import type {
     ResolvedResource,
     RuleInfo,
     SourceSpan,
-    StandardDiagnostic,
-    StandardReport,
     ValidateConfig,
 } from './bindings_wasm';
 export type {
@@ -29,14 +28,12 @@ export type {
     ResourceRef,
     RelatedResource,
     ViolationContext,
-    StandardDiagnostic,
-    DetailedDiagnostic,
+    Diagnostic,
     PhaseMetric,
     PerformanceMetrics,
     Summary,
     ReportMetadata,
-    StandardReport,
-    DetailedReport,
+    ValidationReport,
     PseudoParameterOverrides,
     ValidateConfig,
     ExternalRuleSource,
@@ -79,9 +76,55 @@ export type JsonValue =
     | {
           [key: string]: JsonValue;
       };
+export type AwsCliOperationKind =
+    | 'READ_ONLY'
+    | 'CLOUD_FORMATION_CREATE'
+    | 'CLOUD_FORMATION_UPDATE'
+    | 'CLOUD_FORMATION_DELETE'
+    | 'DATA_PLANE_MUTATION'
+    | 'UNMAPPED_MUTATION';
+export type AwsCliCommandValidationStatus = 'VALIDATED' | 'SKIPPED';
+export type AwsCliTemplateSource =
+    'TEMPLATE_BODY' | 'CLOUD_CONTROL_DESIRED_STATE' | 'SYNTHESIZED_CREATE' | 'SYNTHESIZED_UPDATE';
+export interface AwsCliCommandOptions {
+    servicePrefix?: string;
+    httpMethod?: string;
+    isReadOnly?: boolean;
+}
+/**
+ * Service, operation, and input values for one AWS CLI command.
+ *
+ * `serviceName` is the canonical botocore service name and is normalized only
+ * for ASCII case. Callers adapting an SDK request must translate its native
+ * service identity before constructing this request; endpoint and signing-name
+ * aliases are never guessed by the validation core.
+ */
+export declare class AwsCliCommand {
+    readonly serviceName: string;
+    readonly operationName: string;
+    readonly parameters: Record<string, unknown>;
+    readonly servicePrefix?: string;
+    readonly httpMethod?: string;
+    readonly isReadOnly?: boolean;
+    constructor(
+        serviceName: string,
+        operationName: string,
+        parameters: Record<string, unknown>,
+        options?: AwsCliCommandOptions,
+    );
+}
+export interface AwsCliCommandValidation {
+    operationKind: AwsCliOperationKind;
+    status: AwsCliCommandValidationStatus;
+    templateSource: AwsCliTemplateSource | null;
+    resourceTypes: string[];
+    reason: string;
+    report: ValidationReport | null;
+    template: Uint8Array | null;
+}
 export interface Engine {
-    validateStandard(template: TemplateFile, config?: ValidateConfig): StandardReport;
-    validateDetailed(template: TemplateFile, config?: ValidateConfig): DetailedReport;
+    validateTemplate(template: TemplateFile, config?: ValidateConfig): ValidationReport;
+    validateAwsCliCommand(request: AwsCliCommand): AwsCliCommandValidation;
     listRules(): RuleInfo[];
     engineName(): string;
     free(): void;
@@ -119,6 +162,24 @@ export interface EngineConfig {
      */
     schemaValidatorConfig?: SchemaValidatorConfig;
 }
+/**
+ * Configuration for the {@link CompositeEngine}. The built-in rules are always
+ * evaluated by the engine's fixed built-in evaluator, so these fields only layer
+ * external rules on top - there is no engine-native custom-rule field.
+ */
+export interface CompositeEngineConfig {
+    /** Custom Rego rules layered on top of the built-in rules. */
+    regoRules?: RuleSource[];
+    /** Custom CEL rules layered on top of the built-in rules. */
+    celRules?: RuleSource[];
+    /** CloudFormation Guard DSL rules layered on top of the built-in rules. */
+    guardRules?: RuleSource[];
+    /**
+     * Optional schema validator configuration, observed by both the built-in and
+     * external rule evaluation.
+     */
+    schemaValidatorConfig?: SchemaValidatorConfig;
+}
 /**
  * Configuration for the schema validator. Additional schemas are merged on top
  * of the bundled CloudFormation provider schemas before schema validation.
@@ -150,9 +211,10 @@ export declare class SchemaValidator {
     constructor(config?: SchemaValidatorConfig);
     listRules(): RuleInfo[];
     schemaCount(): number;
-    validate(template: TemplateFile, region?: string): StandardDiagnostic[];
+    validate(template: TemplateFile, region?: string): Diagnostic[];
     free(): void;
 }
 export declare const RegoEngine: new (config?: EngineConfig) => Engine;
 export declare const CelEngine: new (config?: EngineConfig) => Engine;
+export declare const CompositeEngine: new (config?: CompositeEngineConfig) => Engine;
 export declare function version(): string;

package/index.js

@@ -1,15 +1,203 @@
 'use strict';
 Object.defineProperty(exports, '__esModule', { value: true });
-exports.CelEngine =
+exports.CompositeEngine =
+    exports.CelEngine =
     exports.RegoEngine =
     exports.SchemaValidator =
     exports.TemplateModel =
     exports.SchemaFile =
     exports.RuleFile =
     exports.TemplateFile =
+    exports.AwsCliCommand =
         void 0;
 exports.version = version;
 const fs_1 = require('fs');
+/**
+ * Service, operation, and input values for one AWS CLI command.
+ *
+ * `serviceName` is the canonical botocore service name and is normalized only
+ * for ASCII case. Callers adapting an SDK request must translate its native
+ * service identity before constructing this request; endpoint and signing-name
+ * aliases are never guessed by the validation core.
+ */
+class AwsCliCommand {
+    constructor(serviceName, operationName, parameters, options = {}) {
+        this.serviceName = serviceName;
+        this.operationName = operationName;
+        if (!isPlainRecord(parameters)) {
+            throw new TypeError('parameters must be a plain object with string keys');
+        }
+        const copiedParameters = Object.create(null);
+        for (const key of Reflect.ownKeys(parameters)) {
+            if (typeof key !== 'string') {
+                throw new TypeError('request parameter names must be strings');
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(parameters, key);
+            if (descriptor === undefined || !('value' in descriptor)) {
+                throw new TypeError(`request parameter ${JSON.stringify(key)} must be a value property`);
+            }
+            copiedParameters[key] = descriptor.value;
+        }
+        this.parameters = copiedParameters;
+        this.servicePrefix = options.servicePrefix;
+        this.httpMethod = options.httpMethod;
+        this.isReadOnly = options.isReadOnly;
+    }
+}
+exports.AwsCliCommand = AwsCliCommand;
+const MIN_SIGNED_64 = -(1n << 63n);
+const MAX_SIGNED_64 = (1n << 63n) - 1n;
+const MAX_UNSIGNED_64 = (1n << 64n) - 1n;
+const MAX_REQUEST_VALUE_DEPTH = 64;
+const DATE_GET_TIME = Date.prototype.getTime;
+const DATE_TO_ISO_STRING = Date.prototype.toISOString;
+const UINT8_ARRAY_FOR_EACH = Uint8Array.prototype.forEach;
+function isPlainRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function unsupportedValue(typeName) {
+    return { type: 'UNSUPPORTED', type_name: typeName };
+}
+function encodeAwsCliValue(value, depth = 0, ancestors = new Set()) {
+    if (depth > MAX_REQUEST_VALUE_DEPTH) {
+        return unsupportedValue('recursion depth exceeded');
+    }
+    if (value === null) {
+        return { type: 'NULL' };
+    }
+    if (typeof value === 'boolean') {
+        return { type: 'BOOLEAN', value };
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            return unsupportedValue('non-finite floating-point number');
+        }
+        if (Number.isInteger(value)) {
+            return Number.isSafeInteger(value)
+                ? { type: 'INTEGER', value }
+                : unsupportedValue('integer outside the JavaScript safe range');
+        }
+        return { type: 'NUMBER', value };
+    }
+    if (typeof value === 'bigint') {
+        if (value >= MIN_SIGNED_64 && value <= MAX_SIGNED_64) {
+            return { type: 'INTEGER', value };
+        }
+        if (value >= 0n && value <= MAX_UNSIGNED_64) {
+            return { type: 'UNSIGNED_INTEGER', value };
+        }
+        return unsupportedValue('integer outside the 64-bit request range');
+    }
+    if (typeof value === 'string') {
+        return { type: 'STRING', value };
+    }
+    if (value instanceof Uint8Array) {
+        const bytes = [];
+        try {
+            UINT8_ARRAY_FOR_EACH.call(value, (byte) => {
+                bytes.push(byte);
+            });
+        } catch {
+            return unsupportedValue('invalid Uint8Array');
+        }
+        return { type: 'BYTES', value: bytes };
+    }
+    if (value instanceof Date) {
+        try {
+            const timestamp = DATE_GET_TIME.call(value);
+            return Number.isFinite(timestamp)
+                ? { type: 'STRING', value: DATE_TO_ISO_STRING.call(value) }
+                : unsupportedValue('invalid Date');
+        } catch {
+            return unsupportedValue('invalid Date');
+        }
+    }
+    if (Array.isArray(value)) {
+        if (ancestors.has(value)) {
+            return unsupportedValue('cyclic array');
+        }
+        ancestors.add(value);
+        try {
+            const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
+            if (
+                lengthDescriptor === undefined ||
+                !('value' in lengthDescriptor) ||
+                !Number.isSafeInteger(lengthDescriptor.value) ||
+                lengthDescriptor.value < 0
+            ) {
+                return unsupportedValue('array with invalid length');
+            }
+            const items = [];
+            for (let index = 0; index < lengthDescriptor.value; index += 1) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                if (descriptor === undefined) {
+                    return unsupportedValue('sparse array');
+                }
+                if (!('value' in descriptor)) {
+                    return unsupportedValue('array with accessor elements');
+                }
+                items.push(encodeAwsCliValue(descriptor.value, depth + 1, ancestors));
+            }
+            return { type: 'ARRAY', items };
+        } finally {
+            ancestors.delete(value);
+        }
+    }
+    if (isPlainRecord(value)) {
+        if (ancestors.has(value)) {
+            return unsupportedValue('cyclic object');
+        }
+        ancestors.add(value);
+        try {
+            const entries = Object.create(null);
+            for (const key of Reflect.ownKeys(value)) {
+                if (typeof key !== 'string') {
+                    return unsupportedValue('mapping with non-string keys');
+                }
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (descriptor === undefined || !('value' in descriptor)) {
+                    return unsupportedValue('mapping with accessor properties');
+                }
+                entries[key] = encodeAwsCliValue(descriptor.value, depth + 1, ancestors);
+            }
+            return { type: 'OBJECT', entries };
+        } finally {
+            ancestors.delete(value);
+        }
+    }
+    return unsupportedValue(typeof value);
+}
+function toWireAwsCliCommand(request) {
+    const parameters = Object.create(null);
+    for (const [name, value] of Object.entries(request.parameters)) {
+        try {
+            parameters[name] = encodeAwsCliValue(value);
+        } catch {
+            parameters[name] = unsupportedValue('request value inspection failed');
+        }
+    }
+    return {
+        serviceName: request.serviceName,
+        operationName: request.operationName,
+        parameters,
+        ...(request.servicePrefix === undefined ? {} : { servicePrefix: request.servicePrefix }),
+        ...(request.httpMethod === undefined ? {} : { httpMethod: request.httpMethod }),
+        ...(request.isReadOnly === undefined ? {} : { isReadOnly: request.isReadOnly }),
+    };
+}
+function fromWireAwsCliCommandValidation(validation) {
+    const template = validation.template;
+    return {
+        ...validation,
+        templateSource: validation.templateSource ?? null,
+        report: validation.report ?? null,
+        template: template == null ? null : Uint8Array.from(template),
+    };
+}
 const bridge = require('./bindings_wasm');
 class TemplateFile {
     constructor(path) {
@@ -62,6 +250,16 @@ function toWasmEngineConfig(config) {
             : undefined,
     };
 }
+function toWasmCompositeEngineConfig(config) {
+    return {
+        regoRules: toExternalRuleSources(config?.regoRules),
+        celRules: toExternalRuleSources(config?.celRules),
+        guardRules: toExternalRuleSources(config?.guardRules),
+        schemaValidatorConfig: config?.schemaValidatorConfig
+            ? toWasmSchemaValidatorConfig(config.schemaValidatorConfig)
+            : undefined,
+    };
+}
 function toWasmSchemaValidatorConfig(config) {
     return {
         additionalSchemas: toAdditionalSchemas(config?.additionalSchemas),
@@ -126,16 +324,19 @@ class SchemaValidator {
     }
 }
 exports.SchemaValidator = SchemaValidator;
-function createEngineClass(WasmClass) {
+function createEngineClass(WasmClass, toWasmConfig) {
     return class {
         constructor(config) {
-            this.inner = new WasmClass(toWasmEngineConfig(config));
+            this.inner = new WasmClass(toWasmConfig(config));
         }
-        validateStandard(template, config) {
-            return this.inner.validateStandard(template.readBytes(), config ?? {}, template.path);
+        validateTemplate(template, config) {
+            return this.inner.validateTemplate(template.readBytes(), config ?? {}, template.path);
         }
-        validateDetailed(template, config) {
-            return this.inner.validateDetailed(template.readBytes(), config ?? {}, template.path);
+        validateAwsCliCommand(request) {
+            if (!(request instanceof AwsCliCommand)) {
+                throw new TypeError('request must be an AwsCliCommand');
+            }
+            return fromWireAwsCliCommandValidation(this.inner.validateAwsCliCommand(toWireAwsCliCommand(request)));
         }
         listRules() {
             return this.inner.listRules();
@@ -148,8 +349,9 @@ function createEngineClass(WasmClass) {
         }
     };
 }
-exports.RegoEngine = createEngineClass(bridge.WasmRegoEngine);
-exports.CelEngine = createEngineClass(bridge.WasmCelEngine);
+exports.RegoEngine = createEngineClass(bridge.WasmRegoEngine, toWasmEngineConfig);
+exports.CelEngine = createEngineClass(bridge.WasmCelEngine, toWasmEngineConfig);
+exports.CompositeEngine = createEngineClass(bridge.WasmCompositeEngine, toWasmCompositeEngineConfig);
 function version() {
     return bridge.version();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/cloudformation-validate",
-  "version": "1.9.0-beta",
+  "version": "1.10.0",
   "description": "Fast, offline, embeddable validation for AWS CloudFormation templates",
   "keywords": [
     "aws",