Security Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The nth-check module is designed to parse and compile CSS nth-child formulas into optimized JavaScript functions. Security within this project focuses on robust input validation during the parsing phase and ensuring predictable, safe execution during the compilation and generation phases. By strictly adhering to the W3C CSS3 Selectors specification, the module prevents the execution of arbitrary code and mitigates risks associated with malformed selector expressions.
The library is maintained with a focus on high performance and correctness, utilizing automated linting and formatting tools to maintain code quality and prevent common programming errors that could lead to vulnerabilities.
Sources: README.md:9-12, src/parse.ts:1-5, biome.json:30-70
Vulnerability Reporting
The project provides a clear channel for reporting security issues. Users and researchers are encouraged to use the Tidelift security contact for coordinated disclosure.
| Contact Method | Purpose |
|---|---|
| Tidelift Security Contact | Reporting security vulnerabilities and coordinating fixes. |
Sources: README.md:120-123
Input Parsing and Validation
The parse function acts as the primary gatekeeper for the library. It processes raw string formulas and converts them into a structured numeric tuple [a, b]. To maintain security and stability, the parser implements several defensive measures.
Robust Tokenization
The parser explicitly handles whitespace as defined by the W3C spec ( \t\r\n\f) and enforces strict character checks for signs (+, -) and numeric digits.
The diagram above illustrates the linear and restrictive path an input string must follow to be considered valid.
Error Handling
If a formula does not strictly match the expected nth-rule format, the parser throws an Error. This prevents the system from proceeding with ambiguous or potentially malicious input.
// Example of strict validation in src/parse.ts
if (number === null || index < formula.length) {
throw new Error(`n-th rule couldn't be parsed ('${formula}')`);
}
Sources: src/parse.ts:19-75, src/parse.spec.ts:7-11
Secure Compilation and Execution
Once parsed, the compile and generate functions transform the numeric tuple into executable functions. The security here lies in the deterministic nature of the generated logic.
Safe Logic Flow
The compiler uses predefined logic branches to handle specific cases (like a=0 or a=1) and uses mathematical operations like Math.abs and modulo for general cases. This avoids the use of eval() or other dynamic execution sinks.
- Zero-Indexing Conversion: The library internally converts 1-based CSS indices to 0-based JavaScript indices by subtracting 1 from
b. - Fallback to boolbase: If a rule is mathematically impossible to match (e.g., negative steps with negative offsets), the library returns
boolbase.falseFunc, ensuring a safe and performant "no-match" state.
Sources: src/compile.ts:25-52, src/index.ts:18-21
Memory and Performance
To prevent Denial of Service (DoS) via complex selectors, the library optimizes the returned functions to use simple arithmetic. The generate function also ensures that sequences are always increasing, preventing infinite loops or memory exhaustion when iterating through matches.
Sources: src/compile.ts:89-115
Development and Dependency Security
The project employs several tools to ensure the integrity of the codebase and its dependencies.
Dependency Management
The project relies on a minimal dependency tree, specifically boolbase. This reduces the attack surface related to supply chain vulnerabilities.
Quality Control and Linting
The library uses biome and eslint with strict rules to prevent suspicious code patterns.
| Rule Category | Security Impact |
|---|---|
suspicious | Prevents constant binary expressions and ensures correct await usage. |
complexity | Prevents useless logic that could hide bugs. |
performance | Enforces top-level Regex to avoid repeated compilation overhead. |
Sources: package.json:75-80, biome.json:33-50
Summary
Security in nth-check is achieved through strict adherence to the CSS specification and a "fail-fast" parsing strategy. By validating inputs thoroughly in src/parse.ts and generating deterministic arithmetic functions in src/compile.ts, the library ensures that nth-child evaluation remains safe, predictable, and performant for the consumer.