This commit introduces a comprehensive set of improvements to the error handling and loading mechanism of the WebAssembly (WASM) module.
The key changes include:
- **Structured Error Handling:** Replaced generic string-based errors with a structured `WasmError` type in the Go WASM wrapper. This provides standardized error codes (`bad_request`, `not_found`, `conflict`) and clear messages, allowing JavaScript clients to handle errors programmatically.
- **Isomorphic WASM Loader:** Refactored the JavaScript loader (`loader.js`) to be isomorphic, enabling it to run seamlessly in both browser and Node.js environments. The loader now detects the environment and uses the appropriate mechanism for loading the WASM binary and `wasm_exec.js`.
- **Type Conversion Fix:** Resolved a panic (`panic: ValueOf: invalid value`) that occurred when returning `[]float64` slices from Go to JavaScript. A new `pointToJS` helper function now correctly converts these slices to `[]any`, ensuring proper data marshalling.
- **Improved Smoke Test:** Enhanced the WASM smoke test (`smoke.mjs`) to verify the new structured error handling and to correctly handle the API's response format.
- **Configuration Updates:** Updated the `.golangci.yml` configuration to be compatible with the latest version of `golangci-lint`.
In addition to these changes, this commit also includes a new `AUDIT-ERROR-HANDLING.md` file, which documents the findings of a thorough audit of the project's error handling and logging practices.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
Decomposed the "God Class" `kdtree_analytics.go` into three distinct files:
- `kdtree_analytics.go`: Core tree analytics
- `peer_trust.go`: Peer trust scoring logic
- `nat_metrics.go`: NAT-related metrics
Renamed `ComputeDistanceDistribution` to `ComputeAxisDistributions` for clarity.
Created `AUDIT-API.md` to document the findings and changes.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit fixes linting errors in `dns_tools.go` by handling the unchecked error returned from `resp.Body.Close()`. This resolves the CI failures.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces a security audit of the codebase against the OWASP Top 10.
The key findings and remediations include:
- A06: Vulnerable and Outdated Components - Identified that the project's Go version was outdated. The audit report recommends an upgrade.
- A10: Server-Side Request Forgery (SSRF) - Remediated an SSRF vulnerability in the RDAP lookup functions by sanitizing user-provided input with `url.PathEscape`.
- A03: Injection - Mitigated a potential injection vector in the DNS lookup functions by adding a regex-based validation for domain names.
An `AUDIT-OWASP.md` file has been added to the repository root to document these findings and actions taken.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces a comprehensive performance audit of the Poindexter library, as requested. The audit is documented in the `AUDIT-PERFORMANCE.md` file and covers the following areas:
- Database Performance (N/A)
- Memory Usage
- Concurrency
- API Performance (N/A)
- Build/Deploy Performance
The audit includes an analysis of the two k-d tree backends (`linear` and `gonum`) and is supported by benchmark data and memory profiles, which are also included in this commit. The findings provide a clear overview of the library's performance characteristics and identify areas for potential optimization.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit addresses the need for more comprehensive documentation by first conducting an audit to identify gaps and then creating the necessary documentation to fill them.
The following files have been added:
- `AUDIT-DOCUMENTATION.md`: A detailed audit of the project's documentation, evaluating its completeness and quality.
- `ARCHITECTURE.md`: A high-level overview of the project's architecture, including a component diagram.
- `docs/FAQ.md`: A frequently asked questions page to help users with common questions.
- `docs/TROUBLESHOOTING.md`: A guide to help users troubleshoot common issues.
These additions will improve the overall quality of the project's documentation, making it more accessible and useful for both new and existing users.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit adds a cryptographic audit report in AUDIT-CRYPTO.md.
The audit was conducted to review the cryptographic implementations in the codebase. The findings indicate that there are no custom or third-party cryptographic implementations present. The use of `math/rand` is confined to non-security-critical test code, and references to `TLSA` in DNS-related files are purely descriptive.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces a new file, `AUDIT-DX.md`, which contains a comprehensive audit of the developer experience for the Poindexter project.
The audit covers:
- Onboarding: Time to first build, dependency management, and documentation clarity.
- Development Workflow: Local development, testing, build system, and tooling.
- Pain Points: Identifies key areas of friction for new contributors.
- Suggestions for Improvement: Provides actionable recommendations to enhance the developer experience.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces a new file, AUDIT-CONCURRENCY.md, which contains a detailed audit of the concurrency and race condition safety of the Poindexter library.
The audit includes:
- Results from running the Go race detector.
- Analysis of goroutine safety for key data structures.
- Review of mutex and context usage.
- Recommendations for developers using the library.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces a comprehensive security audit of the project's dependencies and supply chain. The findings are documented in the `AUDIT-DEPENDENCIES.md` file, which covers:
- A detailed analysis of direct and transitive dependencies for both Go and npm.
- An assessment of lock file usage and best practices.
- A review of supply chain risks, including the build and release processes.
- A vulnerability scan using `govulncheck`, which identified several issues in the Go standard library.
In addition to the audit report, this commit also adds a `package-lock.json` file to the `npm/poindexter-wasm` directory to ensure reproducible builds.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces an audit of the public API of the Poindexter Go library.
The audit covers:
- API design and consistency
- Naming conventions
- Use of generics
- Error handling
- Documentation
- Security considerations
The audit is saved in the `AUDIT-API.md` file.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit adds a new file, AUDIT-TESTING.md, which contains a comprehensive audit of the project's test coverage, quality, and practices.
The audit includes:
- Coverage analysis (line coverage)
- Test quality evaluation
- Identification of missing tests (edge cases, error paths, security, performance)
- Identification of anti-patterns
- A list of suggested tests to improve the test suite.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces a new file, AUDIT-COMPLEXITY.md, which contains a detailed audit of the codebase.
The audit covers:
- Cyclomatic and cognitive complexity
- Code duplication
- Maintainability issues such as God classes, long methods, and parameter lists
- Other code smells
The report provides specific recommendations for refactoring and improving the code's structure and maintainability, including illustrative code examples. The findings are prioritized by their impact.
This audit serves as a guide for future refactoring efforts to improve the overall quality of the codebase.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit adds a security audit report to the project. The audit found no exposed secrets, credentials, or insecure configurations.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit introduces a new audit report, AUDIT-INPUT-VALIDATION.md, which details the security audit of the project's input validation and sanitization.
The report includes:
- An inventory of input entry points.
- An analysis of validation gaps.
- A description of potential injection vectors.
- Remediation recommendations with code examples.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
This commit adds the `AUDIT-AUTH.md` file, which documents the findings of a security audit focused on authentication and authorization mechanisms.
The audit concluded that the Poindexter repository is a Go library for data structures and does not contain any authentication or authorization flows. Therefore, the audit's primary finding is that these security concerns are not applicable to this codebase.
Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
- Add support for 13 additional record types: ALIAS, RP, SSHFP, TLSA,
DS, DNSKEY, NAPTR, LOC, HINFO, CERT, SMIMEA, WR (Web Redirect), SPF
- Add GetDNSRecordTypeInfo() for metadata with RFC references
- Add GetCommonDNSRecordTypes() for commonly used types
- Add structured types for CAA, SSHFP, TLSA, DS, DNSKEY, NAPTR, RP,
LOC, ALIAS, and WebRedirect records
- Export new functions in WASM bindings
- Update TypeScript definitions and loader.js
- Add comprehensive tests for new record types
Add comprehensive DNS tools module for network analysis:
DNS Lookup functionality:
- Support for A, AAAA, MX, TXT, NS, CNAME, SOA, PTR, SRV, CAA records
- DNSLookup() and DNSLookupAll() for single/complete lookups
- Configurable timeouts
- Structured result types for all record types
RDAP (new-style WHOIS) support:
- RDAPLookupDomain() for domain registration data
- RDAPLookupIP() for IP address information
- RDAPLookupASN() for autonomous system info
- Built-in server registry for common TLDs and RIRs
- ParseRDAPResponse() for extracting key domain info
External tool link generators:
- GetExternalToolLinks() - 20+ links for domain analysis
- GetExternalToolLinksIP() - IP-specific analysis tools
- GetExternalToolLinksEmail() - Email/domain verification
Tools include: MXToolbox (DNS, MX, SPF, DMARC, DKIM, blacklist),
DNSChecker, ViewDNS, IntoDNS, DNSViz, SecurityTrails, SSL Labs,
Shodan, Censys, IPInfo, AbuseIPDB, VirusTotal, and more.
WASM bindings expose link generators and RDAP URL builders
for use in TypeScript/browser environments.
Add comprehensive networking analytics to support peer selection based
on performance and trust metrics for KD-Tree based NAT routing:
- Add kdtree_analytics.go with TreeAnalytics, PeerAnalytics,
DistributionStats, NATRoutingMetrics, TrustMetrics, and
QualityWeights structures
- Track query/insert/delete operations with timing statistics
- Track per-peer selection frequency and average distances
- Add PeerQualityScore() for composite peer ranking
- Add ComputeTrustScore() for reputation-based selection
- Add distribution statistics (min, max, mean, median, percentiles)
- Add feature normalization helpers for multi-dimensional peer data
WASM/TypeScript integration:
- Expose all analytics via WASM bindings
- Update TypeScript definitions with full type coverage
- Update loader.js with new API methods
- Update TypeScript demo to showcase analytics features
Includes comprehensive test coverage for all analytics functionality.
This commit introduces a comprehensive test suite for the `gonum` backend, which was previously untested. It also adds tests for the `kdtree_helpers` package, specifically for the `ComputeNormStats3D` and `BuildND` functions.
The new tests cover a wide range of scenarios, including:
- Basic functionality of `Nearest`, `KNearest`, and `Radius`
- Edge cases such as empty trees, zero/negative inputs, and mismatched dimensions
- Various data configurations, including collinear points and negative coordinates
This commit also includes minor fixes to the existing tests to improve their robustness and accuracy.
As a result of these changes, the overall test coverage of the project has been increased from 80% to over 90%.
