@wtasnorg/node-lib 0.0.7 → 0.0.9

package/gen-docs/002_api.txt

@@ -0,0 +1,34 @@
+# 002 API Surface Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Public Exports (index.ts)
+
+- hello
+- pojo
+- createFindDirectories
+- FindDirectoriesOptions (type)
+- FileSystemDependencies (type)
+
+## Issues Found
+
+### [ISSUE] user-agent.ts - parseUserAgent not exported from index.ts
+
+The main UA parsing function is exported from user-agent.ts but NOT re-exported from index.ts.
+
+```typescript
+// index.ts - missing:
+import { parseUserAgent, UserAgentInfo } from "./user-agent.js";
+export { parseUserAgent };
+export type { UserAgentInfo };
+```
+
+Recommendation: Add to public API.
+
+### [MINOR] user-agent.ts - Helper functions not exported
+
+detectBrowser, detectOS, detectDeviceType, detectEngine are private.
+This is correct - they are implementation details.
+
+## Status
+
+FAIL - parseUserAgent not in public API.

package/gen-docs/002_deps.txt

@@ -0,0 +1,46 @@
+# 002 Dependency Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+Dependencies flow correctly. No circular dependencies. Clean architecture.
+
+## Per-Module Analysis
+
+### find.ts ✅
+- Imports: node:path (resolve, join)
+- Dependencies injected via factory pattern
+- No framework coupling
+
+### hello.ts ✅
+- No imports
+- Uses only global console (acceptable)
+
+### pojo.ts ✅
+- No imports
+- Pure utility function
+
+### user-agent.ts ✅
+- No imports
+- Pure parsing logic
+
+### index.ts ✅
+- Re-exports from modules
+- Clean public API surface
+
+## Issues Found
+
+### [MINOR] find.ts - Unused `stat` dependency
+
+```typescript
+interface FileSystemDependencies {
+    readdir: ...
+    stat: ... // Declared but never used
+}
+```
+
+Recommendation: Remove if not planned for use.
+
+## Status
+
+PASS - Minor cleanup opportunity.

package/gen-docs/002_errors.txt

@@ -0,0 +1,34 @@
+# 002 Error Handling Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+Minimal error handling needed. Functions are defensive.
+
+## Per-Module Analysis
+
+### find.ts ⚠️
+- No explicit error handling for readdir failures
+- Errors will propagate as Promise rejection
+- Acceptable for utility library
+
+### hello.ts ✅
+- Guards console access: `if (console?.log)`
+- No errors expected
+
+### pojo.ts ✅
+- Pure function, no errors expected
+- Handles non-objects via Object.entries (returns [])
+
+### user-agent.ts ✅
+- Defensive null check: `if (!ua) { return defaults }`
+- Optional chaining on split: `?.split(" ")[0] || "0"`
+- All branches return valid defaults
+
+## Issues Found
+
+None requiring action.
+
+## Status
+
+PASS - Error handling appropriate for library scope.

package/gen-docs/002_naming.txt

@@ -0,0 +1,36 @@
+# 002 Naming Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+Generally good naming. A few opportunities for improvement.
+
+## Issues Found
+
+### [MINOR] user-agent.ts:193-194 - Unreachable condition
+
+```typescript
+if (ua.includes("AppleWebKit")) {return "WebKit";}
+if (ua.includes("Blink") || (ua.includes("Chrome/") && ua.includes("AppleWebKit/"))) {return "Blink";}
+```
+
+The second condition can never be fully reached because "AppleWebKit" already returns "WebKit".
+Chrome uses AppleWebKit but should return "Blink".
+
+Recommendation: Reorder conditions - check for Chrome/AppleWebKit combo first.
+
+### [OK] find.ts - createFindDirectories
+
+Factory name is accurate. Returns findDirectories function.
+
+### [OK] pojo.ts - pojo
+
+Short but descriptive. Common abbreviation.
+
+### [OK] user-agent.ts - detectBrowser, detectOS, etc.
+
+Verb prefix indicates action. Clear intent.
+
+## Status
+
+PASS with one logic issue noted.

package/gen-docs/002_notes.txt

@@ -0,0 +1,20 @@
+# 002 Refinement Notes
+Generated: 2026-01-19T20:43:05+05:30
+
+## Action Items
+
+1. **[API]** Export parseUserAgent and UserAgentInfo from index.ts
+2. **[BUG]** Fix detectEngine logic - "Blink" never returned due to ordering
+3. **[CLEANUP]** Consider removing unused `stat` from FileSystemDependencies
+
+## Deferred
+
+- Coverage improvements (find.js 64.71%) - separate iteration
+
+## Summary
+
+Code quality is high. Two issues found:
+1. Missing public export (API gap)
+2. Logic bug in detectEngine (Blink detection)
+
+Both are low-effort fixes.

package/gen-docs/002_purity.txt

@@ -0,0 +1,36 @@
+# 002 Purity & Side-Effect Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+Excellent purity. Side effects isolated and intentional.
+
+## Per-Module Analysis
+
+### find.ts ✅
+- I/O injected, not hardcoded
+- Pure computation inside walk()
+- Side effects (readdir) at boundary via dependency injection
+
+### hello.ts ⚠️
+- console.log is a side effect
+- Mitigated: guarded with `if (console?.log)`
+- Acceptable: function purpose is verification output
+
+### pojo.ts ✅
+- Pure function
+- No side effects
+- Deterministic output
+
+### user-agent.ts ✅
+- All functions pure
+- String parsing only
+- No I/O, no mutation
+
+## Issues Found
+
+None requiring action.
+
+## Status
+
+PASS - Side effects appropriately isolated.

package/gen-docs/002_scope.txt

@@ -0,0 +1,28 @@
+# 002 Scope - Refinement Iteration
+Generated: 2026-01-19T20:43:05+05:30
+
+## In Scope
+
+Modules:
+- find.ts - Directory traversal factory
+- hello.ts - Library health check
+- pojo.ts - Object conversion utility
+- user-agent.ts - UA string parser
+- index.ts - Public exports
+
+## Out of Scope
+
+- Test files (*.test.ts)
+- Generated files (*.js, *.d.ts)
+- Build/tooling configuration
+
+## Assumptions
+
+- Library is functional; tests pass
+- No breaking API changes desired
+- Focus: code quality, not features
+
+## Constraints
+
+- Must maintain backward compatibility
+- All changes require passing tests

package/gen-docs/002_srp.txt

@@ -0,0 +1,34 @@
+# 002 SRP Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+All modules have good single responsibility. No major violations.
+
+## Per-Module Analysis
+
+### find.ts ✅
+- Single concern: directory traversal with filtering
+- Pure factory pattern isolates FS dependencies
+- Helper functions (isAllowed, isBlocked) are cohesive
+
+### hello.ts ✅
+- Single concern: library health check
+- Minor: console.log side effect is appropriate for purpose
+
+### pojo.ts ✅
+- Single concern: class-to-POJO conversion
+- Pure function, no side effects
+
+### user-agent.ts ✅
+- Single concern: UA string parsing
+- Well-decomposed: detectBrowser, detectOS, detectDeviceType, detectEngine
+- Each sub-function has single responsibility
+
+## Issues Found
+
+None requiring action.
+
+## Status
+
+PASS - All modules satisfy SRP.

package/gen-sec/001_base64_security.txt

@@ -0,0 +1,75 @@
+# Base64 Module Security Assessment
+# Date: 2026-01-19
+# Scope: src/base64.ts
+
+## Attack Surface Inventory
+- encode(input: string, charset): accepts user-controlled string
+- decode(input: string, charset): accepts user-controlled Base64 string
+- No network I/O, no file I/O, no exec
+
+## Threat Model
+- Attacker model: untrusted string input
+- Assets: application stability, memory
+- Trust boundary: function input parameters
+
+## OWASP Top 10 Review
+
+### A01 - Broken Access Control
+- N/A: Pure computation, no access control
+
+### A02 - Cryptographic Failures
+- N/A: Not a cryptographic function (encoding != encryption)
+- Note: radix64 is named for OpenPGP but is just Base64 alphabet
+
+### A03 - Injection
+- N/A: No SQL, command, or template execution
+- Output is string manipulation only
+
+### A04 - Insecure Design
+- PASS: Input validation on decode via lookup table
+- PASS: Invalid characters throw explicit error
+
+### A05 - Security Misconfiguration
+- N/A: No configuration, pure library code
+
+### A06 - Vulnerable Components
+- N/A: No external dependencies
+
+### A07 - Identification & Authentication
+- N/A: No auth logic
+
+### A08 - Software & Data Integrity
+- N/A: No deserialization or external data
+
+### A09 - Logging & Monitoring
+- N/A: Library code, no logging (appropriate)
+
+### A10 - SSRF
+- N/A: No URL handling
+
+## Denial of Service Analysis
+- Large input: TextEncoder/TextDecoder handle arbitrary sizes
+- Memory: proportional to input size (expected for encoding)
+- No regex catastrophic backtracking (simple /=+$/ pattern)
+- No infinite loops: bounded by input length
+
+## Input Validation
+- encode(): accepts any valid JS string, converts via TextEncoder
+- decode(): validates each character against charset lookup table
+- Invalid input: throws Error immediately (fail-fast)
+
+## Memory Safety
+- Uses Uint8Array and standard JS arrays
+- No buffer overflows possible in JS/TS
+- No manual memory management
+
+## Findings
+Severity: NONE
+
+## Summary
+No security issues identified. The module is a pure computation library with:
+- No external I/O
+- No dangerous operations
+- Proper input validation
+- Explicit error handling
+- Bounded resource usage

package/gen-sec/001_commands.txt

@@ -0,0 +1,65 @@
+# 001 Commands Executed
+Generated: 2026-01-19T20:46:44+05:30
+
+## Environment Verification
+
+```bash
+which npm node semgrep
+# /home/anubhav/.nvm/versions/node/v24.5.0/bin/npm
+# /home/anubhav/.nvm/versions/node/v24.5.0/bin/node
+# semgrep not found
+
+npm --version
+# 11.7.0
+
+node --version
+# v24.5.0
+```
+
+## Dependency Audit
+
+```bash
+npm audit --json
+# 0 vulnerabilities
+# 131 dependencies (1 prod, 130 dev)
+```
+
+## Static Pattern Analysis
+
+```bash
+# Command injection patterns
+grep -rE 'eval|Function\(|exec|spawn|child_process' src/*.ts
+# No results
+
+# Secret patterns
+grep -riE 'password|secret|api.?key|token|credential' src/*.ts
+# Found: pojo.test.ts (test data only)
+
+# XSS patterns
+grep -rE 'innerHTML|outerHTML|document\.write' src/*.ts
+# No results
+
+# File operation patterns
+grep -rE 'fs\.|readFile|writeFile|unlink|rmdir' src/*.ts
+# No results
+
+# Network patterns
+grep -riE 'http|fetch|axios|request' src/*.ts
+# No results
+
+# Crypto patterns
+grep -riE 'crypto|hash|md5|sha1|sha256' src/*.ts
+# No results
+
+# SQL patterns
+grep -riE 'sql|query|database|db\.' src/*.ts
+# No results
+
+# Deserialization patterns
+grep -rE 'JSON\.parse|deserialize|pickle' src/*.ts
+# No results
+
+# Prototype pollution patterns
+grep -rE 'prototype|__proto__|constructor\[' src/*.ts
+# Found: pojo.ts, pojo.test.ts (documentation/test only)
+```

package/gen-sec/001_env.txt

@@ -0,0 +1,28 @@
+# 001 Environment Verification
+Generated: 2026-01-19T20:46:44+05:30
+
+## Tooling Status
+
+| Tool     | Status    | Version   | Path                                    |
+|----------|-----------|-----------|----------------------------------------|
+| node     | ✅ OK     | v24.5.0   | /home/anubhav/.nvm/versions/node/...   |
+| npm      | ✅ OK     | 11.7.0    | /home/anubhav/.nvm/versions/node/...   |
+| semgrep  | ❌ MISSING| -         | -                                       |
+
+## npm audit
+
+```
+Vulnerabilities: 0
+  - Critical: 0
+  - High: 0
+  - Moderate: 0
+  - Low: 0
+  - Info: 0
+
+Dependencies: 131 (1 prod, 130 dev)
+```
+
+## Notes
+
+- Semgrep not installed; manual pattern analysis performed
+- All dev dependencies, minimal prod footprint

package/gen-sec/001_findings.txt

@@ -0,0 +1,63 @@
+# 001 Security Findings
+Generated: 2026-01-19T20:46:44+05:30
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | 0     |
+| High     | 0     |
+| Medium   | 0     |
+| Low      | 1     |
+| Info     | 1     |
+
+## Findings
+
+### [LOW] F001 - Path Traversal Potential in find.ts
+
+**Location:** find.ts:23-26, createFindDirectories()
+
+**Description:**
+The `root` parameter is passed to `resolve()` without validation.
+If a consumer passes user-controlled input, path traversal is possible.
+
+**Impact:** Directory enumeration outside intended scope.
+
+**Exploitability:** LOW - Requires consumer misuse.
+
+**CWE:** CWE-22 (Path Traversal)
+
+**OWASP:** A01 (Broken Access Control)
+
+**Confidence:** LOW - Library design expects trusted input.
+
+**Recommendation:**
+- Document that `root` must be trusted input
+- Optionally add: validate root is within allowed base path
+
+---
+
+### [INFO] F002 - "secret" String in Test File
+
+**Location:** pojo.test.ts:54-65
+
+**Description:**
+String "secret" appears in test data (SecretBox class).
+
+**Impact:** None - test data only.
+
+**Confidence:** HIGH - Verified as test fixture.
+
+**Recommendation:** No action needed.
+
+---
+
+## Residual Risk
+
+**MINIMAL** - This is a stateless utility library with:
+- No network exposure
+- No database access
+- No authentication
+- No user input handling
+
+Security posture depends on consumer implementation.

package/gen-sec/001_inventory.txt

@@ -0,0 +1,41 @@
+# 001 Attack Surface Inventory
+Generated: 2026-01-19T20:46:44+05:30
+
+## Overview
+
+This is a pure utility library with NO:
+- HTTP endpoints
+- CLI interfaces
+- Database access
+- Authentication
+- Network I/O
+
+## Entry Points
+
+### find.ts - createFindDirectories()
+
+- Input: FileSystemDependencies (injected), root path, options
+- Operations: Directory traversal via injected readdir
+- Trust boundary: Consumer provides FS functions
+
+### hello.ts - hello()
+
+- Input: None
+- Operations: Returns static string, logs to console
+- Trust boundary: None
+
+### pojo.ts - pojo()
+
+- Input: Object instance
+- Operations: Object.entries, Object.fromEntries
+- Trust boundary: Consumer provides object
+
+### user-agent.ts - parseUserAgent()
+
+- Input: String (user-agent)
+- Operations: String parsing (split, includes)
+- Trust boundary: Consumer provides UA string
+
+## Attack Surface Rating
+
+**MINIMAL** - Pure functions, no I/O, no state, no network.

package/gen-sec/001_owasp.txt

@@ -0,0 +1,78 @@
+# 001 OWASP Top 10 Assessment
+Generated: 2026-01-19T20:46:44+05:30
+
+## A01 - Broken Access Control
+
+**N/A** - No authentication, authorization, or access control.
+
+## A02 - Cryptographic Failures
+
+**N/A** - No cryptographic operations.
+- No passwords, tokens, or secrets
+- No hashing or encryption
+
+## A03 - Injection
+
+**LOW RISK** - Pattern analysis performed:
+
+| Pattern              | Found | Files |
+|---------------------|-------|-------|
+| eval()              | ❌ No | -     |
+| Function()          | ❌ No | -     |
+| exec/spawn          | ❌ No | -     |
+| child_process       | ❌ No | -     |
+| SQL                 | ❌ No | -     |
+| innerHTML           | ❌ No | -     |
+
+## A04 - Insecure Design
+
+**N/A** - Simple utility library.
+- No business logic
+- No rate limiting needed
+- No trust assumptions
+
+## A05 - Security Misconfiguration
+
+**N/A** - No configuration surface.
+- No debug modes
+- No CORS
+- No credentials
+
+## A06 - Vulnerable Components
+
+**PASS** - npm audit: 0 vulnerabilities
+- 131 dependencies scanned
+- No known CVEs
+
+## A07 - Identification & Authentication Failures
+
+**N/A** - No authentication.
+
+## A08 - Software & Data Integrity Failures
+
+**LOW RISK** - Analyzed for deserialization:
+
+| Pattern              | Found | Notes                    |
+|---------------------|-------|--------------------------|
+| JSON.parse          | ❌ No | -                        |
+| Prototype pollution | ❌ No | pojo() uses safe methods |
+
+pojo() uses Object.entries/fromEntries which are safe.
+
+## A09 - Logging & Monitoring Failures
+
+**N/A** - Library code, not service.
+- console.log in hello() is benign
+
+## A10 - SSRF
+
+**N/A** - No network I/O.
+- No fetch, axios, http
+- No URL handling
+
+## Summary
+
+| Category | Status |
+|----------|--------|
+| A01-A10  | N/A or PASS |
+| Overall  | **LOW RISK** |

package/gen-sec/001_scope.txt

@@ -0,0 +1,44 @@
+# 001 Scope - Security Assessment
+Generated: 2026-01-19T20:46:44+05:30
+
+## Target
+
+- Package: @wtasnorg/node-lib@0.0.8
+- Type: TypeScript utility library
+- Platform: Node.js
+
+## In Scope
+
+- src/*.ts (source files)
+- Dependencies (package.json)
+- Build artifacts
+
+## Out of Scope
+
+- Test files (contain mock data only)
+- Documentation
+- CI/CD configuration
+
+## Sensitive Data Classes
+
+None identified. Library is stateless and handles:
+- File paths (find.ts)
+- String parsing (user-agent.ts, pojo.ts)
+- No PII, credentials, or financial data
+
+## Allowed Techniques
+
+- Static code analysis
+- Dependency auditing
+- Pattern matching for dangerous APIs
+
+## Forbidden Techniques
+
+- Network scanning (N/A - no network exposure)
+- Dynamic exploitation (N/A - library code)
+
+## Assumptions
+
+- Library runs in trusted Node.js environment
+- Consumers provide trusted inputs
+- No direct user input handling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtasnorg/node-lib",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "node library",
   "main": "src/index.js",
   "scripts": {
@@ -8,7 +8,8 @@
     "docs": "./node_modules/.bin/typedoc",
     "docs:json": "./node_modules/.bin/typedoc --json docs/docs.json",
     "docs:watch": "./node_modules/.bin/typedoc --watch",
-    "test": "bash -c 'node --test src/**/*.test.js'"
+    "test": "bash -c 'node --test src/**/*.test.js'",
+    "lint": "npx eslint src/*.ts --no-warn-ignored"
   },
   "keywords": [
     "library"