|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is **secure-json-parse**, a drop-in replacement for `JSON.parse()` that protects against prototype poisoning attacks. The library detects and handles dangerous `__proto__` and `constructor` properties in JSON that could lead to prototype pollution vulnerabilities. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +- **Single-file module**: `index.js` contains the core functionality |
| 12 | +- **Three main functions**: |
| 13 | + - `parse()`: Main JSON parsing with security checks (supports reviver and options) |
| 14 | + - `scan()` (exported as `filter`): Scans existing objects for dangerous properties |
| 15 | + - `safeParse()`: Returns undefined instead of throwing errors |
| 16 | +- **Security approach**: Uses regex pre-scanning for performance, then deep object traversal for thorough cleanup |
| 17 | +- **Enhanced security**: Now specifically targets `constructor.prototype` patterns rather than any `constructor` property |
| 18 | +- **Action modes**: `error` (default), `remove`, or `ignore` for both `protoAction` and `constructorAction` |
| 19 | +- **TypeScript support**: Includes TypeScript definitions in `types/` directory |
| 20 | + |
| 21 | +## Commands |
| 22 | + |
| 23 | +### Testing |
| 24 | +```bash |
| 25 | +npm test # Run linting, unit tests, and TypeScript tests |
| 26 | +npm run test:unit # Run unit tests only (tape) |
| 27 | +npm run test:typescript # Run TypeScript definition tests (tsd) |
| 28 | +npm run test:browser # Run tests in browsers using airtap |
| 29 | +``` |
| 30 | + |
| 31 | +### Linting |
| 32 | +```bash |
| 33 | +npm run lint # Run ESLint with neostandard config |
| 34 | +npm run lint:fix # Auto-fix linting issues where possible |
| 35 | +``` |
| 36 | + |
| 37 | +### Benchmarking |
| 38 | +```bash |
| 39 | +npm run benchmark # Run performance benchmarks against standard JSON.parse |
| 40 | +``` |
| 41 | + |
| 42 | +### Code Standards |
| 43 | +- Uses **neostandard** with **ESLint 9** for linting |
| 44 | +- **Tape** for testing framework |
| 45 | +- **nyc** for test coverage |
| 46 | +- **tsd** for TypeScript definition testing |
| 47 | +- Test files located in `test/` directory (not root) |
| 48 | + |
| 49 | +### Git Workflow |
| 50 | +- Use `git commit -s` to add Developer Certificate of Origin signoff |
| 51 | +- Create feature branches for changes |
| 52 | +- All commits should include proper signoff for contribution tracking |
| 53 | + |
| 54 | +## Testing Notes |
| 55 | + |
| 56 | +- Tests cover all action combinations (`error`/`remove`/`ignore`) |
| 57 | +- Unicode escape sequence handling is thoroughly tested |
| 58 | +- Buffer and BOM (Byte Order Mark) support included |
| 59 | +- Tests verify behavior with overwritten `hasOwnProperty` |
| 60 | +- Constructor null handling is tested to prevent TypeError |
| 61 | +- Enhanced security tests for `constructor.prototype` patterns specifically |
| 62 | +- TypeScript definitions are validated with test files in `types/` |
0 commit comments