@safe-ugc-ui/validator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Safe UGC UI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,385 @@
+import { UGCCard } from '@safe-ugc-ui/types';
+
+/**
+ * @safe-ugc-ui/validator — Validation Result Types
+ *
+ * Provides the error and result types used throughout the validation pipeline.
+ *
+ * Design decisions:
+ *   - Errors include a `path` for precise location in the card tree.
+ *   - Errors include a `code` for programmatic handling.
+ *   - `merge()` combines multiple results, accumulating all errors.
+ *   - A valid result is simply `{ valid: true, errors: [] }`.
+ */
+/**
+ * Machine-readable error codes for every validation failure type.
+ */
+type ValidationErrorCode = 'INVALID_JSON' | 'MISSING_FIELD' | 'INVALID_TYPE' | 'INVALID_VALUE' | 'UNKNOWN_NODE_TYPE' | 'SCHEMA_ERROR' | 'EXPR_NOT_ALLOWED' | 'REF_NOT_ALLOWED' | 'DYNAMIC_NOT_ALLOWED' | 'FORBIDDEN_STYLE_PROPERTY' | 'STYLE_VALUE_OUT_OF_RANGE' | 'FORBIDDEN_CSS_FUNCTION' | 'INVALID_COLOR' | 'INVALID_LENGTH' | 'FORBIDDEN_OVERFLOW_VALUE' | 'TRANSFORM_SKEW_FORBIDDEN' | 'EXTERNAL_URL' | 'POSITION_FIXED_FORBIDDEN' | 'POSITION_STICKY_FORBIDDEN' | 'POSITION_ABSOLUTE_NOT_IN_STACK' | 'ASSET_PATH_TRAVERSAL' | 'INVALID_ASSET_PATH' | 'PROTOTYPE_POLLUTION' | 'CARD_SIZE_EXCEEDED' | 'TEXT_CONTENT_SIZE_EXCEEDED' | 'STYLE_SIZE_EXCEEDED' | 'NODE_COUNT_EXCEEDED' | 'LOOP_ITERATIONS_EXCEEDED' | 'NESTED_LOOPS_EXCEEDED' | 'OVERFLOW_AUTO_COUNT_EXCEEDED' | 'OVERFLOW_AUTO_NESTED' | 'STACK_NESTING_EXCEEDED' | 'EXPR_TOO_LONG' | 'REF_TOO_LONG' | 'EXPR_TOO_MANY_TOKENS' | 'EXPR_NESTING_TOO_DEEP' | 'EXPR_CONDITION_NESTING_TOO_DEEP' | 'EXPR_REF_DEPTH_EXCEEDED' | 'EXPR_ARRAY_INDEX_EXCEEDED' | 'EXPR_STRING_LITERAL_TOO_LONG' | 'EXPR_FORBIDDEN_TOKEN' | 'EXPR_FUNCTION_CALL' | 'EXPR_INVALID_TOKEN' | 'LOOP_SOURCE_NOT_ARRAY' | 'LOOP_SOURCE_MISSING' | 'STYLE_CIRCULAR_REF' | 'STYLE_REF_NOT_FOUND' | 'INVALID_STYLE_REF' | 'INVALID_STYLE_NAME';
+/**
+ * A single validation error with location and diagnostic info.
+ */
+interface ValidationError {
+    /** Machine-readable error code. */
+    code: ValidationErrorCode;
+    /** Human-readable error message. */
+    message: string;
+    /**
+     * JSON-pointer-like path to the error location.
+     * e.g. `"views.StatusWindow.children[0].style.zIndex"`
+     */
+    path: string;
+}
+/**
+ * The result of running the validation pipeline.
+ *
+ * - `valid: true`  → the card is safe to render.
+ * - `valid: false` → the card has errors; do NOT render.
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Create a single validation error.
+ */
+declare function createError(code: ValidationErrorCode, message: string, path: string): ValidationError;
+/**
+ * Create a valid result (no errors).
+ */
+declare function validResult(): ValidationResult;
+/**
+ * Create an invalid result from a list of errors.
+ */
+declare function invalidResult(errors: ValidationError[]): ValidationResult;
+/**
+ * Wrap errors into a ValidationResult (valid if no errors).
+ */
+declare function toResult(errors: ValidationError[]): ValidationResult;
+/**
+ * Merge multiple validation results into one.
+ * The merged result is valid only if ALL inputs are valid.
+ */
+declare function merge(...results: ValidationResult[]): ValidationResult;
+
+/**
+ * @safe-ugc-ui/validator — Tree Traversal
+ *
+ * Provides utilities for walking the UGC card tree, tracking:
+ *   - path:      JSON-pointer-like location string
+ *   - depth:     nesting level
+ *   - parentType: the type of the parent node (for position/overflow rules)
+ *   - loopDepth: nesting level of for-loops
+ *   - overflowAutoAncestor: whether an ancestor has overflow:auto
+ *   - stackDepth: nesting level of Stack components
+ *
+ * The traversal is generic: it calls a visitor function on each node,
+ * allowing different validators to collect different data.
+ */
+/**
+ * Contextual information available at each node during traversal.
+ */
+interface TraversalContext {
+    /** JSON-pointer-like path, e.g. "views.Main.children[0].children[1]" */
+    path: string;
+    /** Nesting depth (root node = 0). */
+    depth: number;
+    /** The `type` of the immediate parent node, or null for root-level nodes. */
+    parentType: string | null;
+    /** Current for-loop nesting depth (0 = no loop). */
+    loopDepth: number;
+    /** True if any ancestor has `overflow: auto` in its style. */
+    overflowAutoAncestor: boolean;
+    /** Current Stack nesting depth (0 = not inside a Stack). */
+    stackDepth: number;
+}
+/**
+ * Minimal shape expected for a node during traversal.
+ * We use a loose type because traversal runs after schema validation,
+ * but the node might have extra or unexpected fields.
+ */
+interface TraversableNode {
+    type: string;
+    children?: TraversableNode[] | ForLoopLike;
+    style?: Record<string, unknown>;
+    condition?: unknown;
+    [key: string]: unknown;
+}
+interface ForLoopLike {
+    for: string;
+    in: string;
+    template: TraversableNode;
+}
+/**
+ * A visitor function called for every node in the tree.
+ * Return `false` to skip traversing into this node's children.
+ */
+type NodeVisitor = (node: TraversableNode, context: TraversalContext) => void | false;
+/**
+ * Recursively traverse a single node and its descendants.
+ */
+declare function traverseNode(node: TraversableNode, context: TraversalContext, visitor: NodeVisitor): void;
+/**
+ * Traverse all nodes in every view of a card.
+ *
+ * @param views - The `views` object from a UGCCard (mapping view names to root nodes).
+ * @param visitor - Called for every node in every view.
+ */
+declare function traverseCard(views: Record<string, unknown>, visitor: NodeVisitor): void;
+
+/**
+ * @safe-ugc-ui/validator — Schema (Structural) Validation
+ *
+ * Verifies the top-level structure of a UGC card:
+ *   - Required fields: meta (name, version), views (at least one)
+ *   - Zod schema parse for the full card structure
+ *   - Maps Zod parse errors to ValidationError format
+ *
+ * This is the first step in the validation pipeline (after size check).
+ * If structural validation fails, no further checks are performed.
+ */
+
+/**
+ * Validate the structural shape of a card using the Zod schema.
+ *
+ * @param input - An unknown value (already parsed from JSON).
+ * @returns A ValidationResult. If valid, the parsed UGCCard can be accessed
+ *          from the Zod result; callers should re-parse if they need the typed object.
+ */
+declare function validateSchema(input: unknown): ValidationResult;
+/**
+ * Parse a card from an unknown input, returning either the typed UGCCard
+ * or null if structural validation fails.
+ *
+ * Callers should first run `validateSchema()` to get user-facing errors.
+ * This is a convenience for subsequent pipeline stages that need the typed card.
+ */
+declare function parseCard(input: unknown): UGCCard | null;
+
+/**
+ * @safe-ugc-ui/validator — Node Validator
+ *
+ * Validates component type-specific requirements for each node in the card tree.
+ *
+ * For every node encountered during traversal:
+ *   1. Rejects unknown node types not in ALL_COMPONENT_TYPES.
+ *   2. Checks that required fields exist for each component type.
+ *   4. Validates ForLoop structure when children use `for`/`in`/`template`.
+ */
+
+/**
+ * Validate all nodes in every view of a card.
+ *
+ * Uses `traverseCard()` to visit every node and checks:
+ *   - Node type is a known component type.
+ *   - Required fields are present for the given component type.
+ *   - ForLoop children have valid `for`, `in`, and `template` fields.
+ *
+ * @param views - The `views` object from a UGCCard.
+ * @returns An array of validation errors (empty if all nodes are valid).
+ */
+declare function validateNodes(views: Record<string, unknown>): ValidationError[];
+
+/**
+ * @safe-ugc-ui/validator — Value Type Validation
+ *
+ * Validates per-property $ref / $expr permission rules based on spec
+ * section 4.5 value type table.
+ *
+ * | Property Type     | Literal | $ref | $expr |
+ * |-------------------|---------|------|-------|
+ * | Image.src         |   yes   | yes  |  no   |
+ * | Avatar.src        |   yes   | yes  |  no   |
+ * | Icon.name         |   yes   |  no  |  no   |
+ * | Text.content      |   yes   | yes  | yes   |
+ * | Color properties  |   yes   | yes  | yes   |
+ * | Size properties   |   yes   | yes  | yes   |
+ * | position          |   yes   |  no  |  no   |
+ * | transform         |   yes   |  no  |  no   |
+ * | gradient          |   yes   |  no  |  no   |
+ *
+ * Additionally, several style properties must always be static
+ * (no $ref or $expr): overflow, border*, boxShadow, zIndex,
+ * and position offset properties (top/right/bottom/left).
+ */
+
+/**
+ * Walk all nodes in the card and validate that each field's value
+ * respects its allowed value types ($ref / $expr permissions).
+ *
+ * @param views - The `views` object from a UGCCard.
+ * @returns An array of validation errors (empty if all values are valid).
+ */
+declare function validateValueTypes(views: Record<string, unknown>): ValidationError[];
+
+/**
+ * @safe-ugc-ui/validator — Style Validator
+ *
+ * Validates style properties according to the spec's style restrictions:
+ *   - Forbidden CSS properties (spec 3.8)
+ *   - Numeric range limits (spec 6.4)
+ *   - Box-shadow count and value limits
+ *   - Transform skew prohibition
+ *   - Dangerous CSS function injection detection
+ *   - Overflow: scroll prohibition (defense-in-depth)
+ *   - Color format validation
+ *   - Length format validation
+ */
+
+/**
+ * Validate all style properties across every node in the card's view tree,
+ * and validate card-level style definitions.
+ *
+ * Checks:
+ *   1. Forbidden style properties (spec 3.8)
+ *   2. Numeric range limits (spec 6.4)
+ *   3. Box-shadow count and value limits
+ *   4. Transform skew prohibition
+ *   5. CSS function injection in string values
+ *   6. Overflow: scroll prohibition (defense-in-depth)
+ *   7. Color format validation
+ *   8. Length format validation
+ *   9. Range checks on string length values
+ *  10. $style reference validation and merging
+ */
+declare function validateStyles(views: Record<string, unknown>, cardStyles?: Record<string, Record<string, unknown>>): ValidationError[];
+
+/**
+ * @safe-ugc-ui/validator — Security Validation
+ *
+ * Enforces security rules from spec sections 3 and 8:
+ *   - External URL blocking on Image/Avatar `src` fields (literal and $ref)
+ *   - Asset path validation (`@assets/` prefix, no traversal)
+ *   - cardAssets value validation
+ *   - Forbidden CSS `url()` function in style string values
+ *   - Position restrictions (fixed, sticky, absolute outside Stack)
+ *   - Nested overflow:auto detection
+ *   - Prototype pollution prevention in $ref paths
+ */
+
+/**
+ * Run all security validation rules against every node in every view.
+ *
+ * Rules checked (spec sections 3 and 8):
+ *   1. External URL blocking on Image/Avatar `src` (literal and $ref)
+ *   2. Asset path validation
+ *   3. cardAssets value validation
+ *   4. Forbidden CSS `url()` in style string values
+ *   5. Position restrictions (fixed, sticky, absolute outside Stack)
+ *   6. Nested overflow:auto
+ *   7. Prototype pollution in $ref paths
+ *
+ * @param card - Object containing `views`, optional `state`, and optional `cardAssets`.
+ * @returns An array of validation errors (empty if all rules pass).
+ */
+declare function validateSecurity(card: {
+    views: Record<string, unknown>;
+    state?: Record<string, unknown>;
+    cardAssets?: Record<string, string>;
+    cardStyles?: Record<string, Record<string, unknown>>;
+}): ValidationError[];
+
+/**
+ * @safe-ugc-ui/validator — Resource Limits Validation
+ *
+ * Validates resource limits per spec section 6.
+ *
+ * Uses a single traversal pass to collect all metrics (node count,
+ * text content size, style object size, loop iterations, nested loops,
+ * overflow:auto count, and stack nesting), then checks each against the
+ * defined constants from @safe-ugc-ui/types.
+ */
+
+/**
+ * Validate all resource limits defined in spec section 6.
+ *
+ * Performs a single traversal of the card tree, collecting metrics for:
+ *   - Total node count
+ *   - Total text content bytes (UTF-8)
+ *   - Total style object bytes (UTF-8, JSON-serialized)
+ *   - Loop iteration counts
+ *   - Nested loop depth
+ *   - overflow:auto element count
+ *   - Stack nesting depth
+ *
+ * @param card - A card object with optional `state` and required `views`.
+ * @returns An array of validation errors (empty if all limits are satisfied).
+ */
+declare function validateLimits(card: {
+    state?: Record<string, unknown>;
+    views: Record<string, unknown>;
+    cardStyles?: Record<string, Record<string, unknown>>;
+}): ValidationError[];
+
+/**
+ * @safe-ugc-ui/validator -- Expression & Reference Constraint Validation
+ *
+ * Validates $expr and $ref values found in the card tree against the
+ * constraints defined in the spec's "expression constraint" section (6.3).
+ *
+ * A simple tokenizer splits expression strings into typed tokens so that
+ * structural limits (nesting, token count, forbidden operators) can be
+ * checked without executing the expression.
+ */
+
+/**
+ * Validates all $expr and $ref values found in the card's views.
+ *
+ * Uses tree traversal to visit every node, then deep-scans each node's
+ * flattened node fields and `style` (and `condition`) for dynamic values.
+ *
+ * @param views - The `views` object from a UGCCard.
+ * @returns An array of validation errors (empty if all constraints pass).
+ */
+declare function validateExprConstraints(views: Record<string, unknown>): ValidationError[];
+
+/**
+ * @safe-ugc-ui/validator — Public API
+ *
+ * Provides two entry points for card validation:
+ *
+ *   validateRaw(rawJson: string) — Recommended for raw JSON strings.
+ *     Checks UTF-8 byte size BEFORE parsing. If too large, rejects without
+ *     parsing (DoS prevention). Returns ValidationResult.
+ *
+ *   validate(input: unknown) — For already-parsed objects.
+ *     Skips size check. Returns ValidationResult.
+ *
+ * Pipeline:
+ *   1. (validateRaw only) UTF-8 byte size check (1MB limit)
+ *   2. (validateRaw only) JSON.parse — parse error → ValidationResult
+ *   3. Schema validation → fail → early return
+ *   4. All remaining checks run, errors accumulated:
+ *      node → value-types → style → security → limits → expr-constraints
+ */
+
+/**
+ * Validate an already-parsed card object.
+ *
+ * Skips the JSON byte size check (use `validateRaw` for raw strings).
+ *
+ * Pipeline:
+ *   1. Schema validation → fail → early return
+ *   2. All remaining checks (node, value-types, style, security, limits, expr)
+ *
+ * @param input - An unknown value (typically parsed JSON).
+ * @returns A ValidationResult — safe to render only if `valid` is true.
+ */
+declare function validate(input: unknown): ValidationResult;
+/**
+ * Validate a raw JSON string. Recommended entry point.
+ *
+ * Checks the byte size of the raw string BEFORE parsing to prevent
+ * JSON parsing DoS with oversized payloads.
+ *
+ * Pipeline:
+ *   1. UTF-8 byte size check (1MB max) → reject without parsing
+ *   2. JSON.parse → parse error → ValidationResult (no throw)
+ *   3. Schema validation → fail → early return
+ *   4. All remaining checks
+ *
+ * @param rawJson - A raw JSON string representing a UGC card.
+ * @returns A ValidationResult — safe to render only if `valid` is true.
+ */
+declare function validateRaw(rawJson: string): ValidationResult;
+
+export { type NodeVisitor, type TraversableNode, type TraversalContext, type ValidationError, type ValidationErrorCode, type ValidationResult, createError, invalidResult, merge, parseCard, toResult, traverseCard, traverseNode, validResult, validate, validateExprConstraints, validateLimits, validateNodes, validateRaw, validateSchema, validateSecurity, validateStyles, validateValueTypes };