@wtasnorg/node-lib 0.0.6 → 0.0.8

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_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.6",
+  "version": "0.0.8",
   "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"
@@ -27,9 +28,15 @@
     "url": "git+https://github.com/wtasg/node-lib.git"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@stylistic/eslint-plugin": "^5.6.1",
     "@types/node": "^24.10.1",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^16.5.0",
     "typedoc": "^0.28.15",
     "typedoc-plugin-markdown": "^4.9.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1"
   }
 }

package/{README.md → readme.txt}

@@ -9,6 +9,8 @@ A library project for nodejs. #nodejs #typescript #library
 
 1. hello (for debugging)
 2. `pojo` for converting class objects to Plain Old Javascript Objects.
+3. `createFindDirectories` as a factory for finding directories; think `find path -type d`.
+4. `parseUserAgent` for extracting information from user-agent strings.
 
 ## Develop
 
@@ -31,7 +33,7 @@ npm install @wtasnorg/node-lib
 # check if you can run code
 import {hello} from "@wtasnorg/node-lib";
 
-await hello(); 
+await hello();
 // "hello from @wtasnorg/node-lib"
 ```
 

package/src/find.d.ts

@@ -1,19 +1,19 @@
 interface FileSystemDependencies {
-    readdir: (path: string, opts: {
+    readdir: (_path: string, _opts: {
         withFileTypes: true;
     }) => Promise<{
         name: string;
         isDirectory(): boolean;
     }[]>;
-    stat: (path: string) => Promise<{
+    stat: (_path: string) => Promise<{
         isDirectory(): boolean;
     }>;
 }
 interface FindDirectoriesOptions {
     maxDepth?: number;
     followSymlinks?: boolean;
-    allowlist?: string[] | ((absPath: string, name: string) => boolean);
-    blocklist?: string[] | ((absPath: string, name: string) => boolean);
+    allowlist?: string[] | ((_absPath: string, _name: string) => boolean);
+    blocklist?: string[] | ((_absPath: string, _name: string) => boolean);
 }
 /**
  * Factory that produces an async findDirectories function with

package/src/find.js

@@ -12,8 +12,9 @@ function createFindDirectories(deps) {
         function isAllowed(absPath, name) {
             if (allowlist) {
                 if (Array.isArray(allowlist)) {
-                    if (!allowlist.includes(name))
+                    if (!allowlist.includes(name)) {
                         return false;
+                    }
                 }
                 else if (!allowlist(absPath, name)) {
                     return false;
@@ -24,8 +25,9 @@ function createFindDirectories(deps) {
         function isBlocked(absPath, name) {
             if (blocklist) {
                 if (Array.isArray(blocklist)) {
-                    if (blocklist.includes(name))
+                    if (blocklist.includes(name)) {
                         return true;
+                    }
                 }
                 else if (blocklist(absPath, name)) {
                     return true;
@@ -34,18 +36,22 @@ function createFindDirectories(deps) {
             return false;
         }
         async function walk(currentPath, depth) {
-            if (depth > maxDepth)
+            if (depth > maxDepth) {
                 return;
+            }
             const entries = await readdir(currentPath, { withFileTypes: true });
             for (const entry of entries) {
                 const childPath = resolve(join(currentPath, entry.name));
-                let isDirectory = entry.isDirectory();
-                if (!isDirectory)
+                const isDirectory = entry.isDirectory();
+                if (!isDirectory) {
                     continue;
-                if (isBlocked(childPath, entry.name))
+                }
+                if (isBlocked(childPath, entry.name)) {
                     continue;
-                if (!isAllowed(childPath, entry.name))
+                }
+                if (!isAllowed(childPath, entry.name)) {
                     continue;
+                }
                 results.push(childPath);
                 if (depth < maxDepth) {
                     await walk(childPath, depth + 1);

package/src/find.test.js

@@ -58,10 +58,8 @@ test("find: findDirectories symlink is NOT treated as a directory", async () =>
     ]);
 });
 test("find: findDirectories at depth=2", async () => {
-    const calls = [];
     const deps = {
         readdir: async (path) => {
-            calls.push(path);
             switch (path) {
                 case "/root":
                     return [dir("a"), dir("b"), file("ignore.txt")];
@@ -73,7 +71,7 @@ test("find: findDirectories at depth=2", async () => {
                     return [];
             }
         },
-        stat: async (_) => ({
+        stat: async () => ({
             isDirectory: () => false
         })
     };
@@ -88,10 +86,8 @@ test("find: findDirectories at depth=2", async () => {
     ].sort());
 });
 test("find: findDirectories at depth=3", async () => {
-    const calls = [];
     const deps = {
         readdir: async (path) => {
-            calls.push(path);
             switch (path) {
                 case "/root":
                     return [dir("a"), dir("b")];
@@ -108,7 +104,7 @@ test("find: findDirectories at depth=3", async () => {
                     return [];
             }
         },
-        stat: async (_) => ({
+        stat: async () => ({
             isDirectory: () => false
         })
     };

package/src/find.test.ts

@@ -77,12 +77,8 @@ test("find: findDirectories symlink is NOT treated as a directory", async () =>
 
 
 test("find: findDirectories at depth=2", async () => {
-    const calls: string[] = [];
-
     const deps: FileSystemDependencies = {
         readdir: async (path: string): Promise<{ name: string; isDirectory(): boolean }[]> => {
-            calls.push(path);
-
             switch (path) {
                 case "/root":
                     return [dir("a"), dir("b"), file("ignore.txt")];
@@ -94,7 +90,7 @@ test("find: findDirectories at depth=2", async () => {
                     return [];
             }
         },
-        stat: async (_: string) => ({
+        stat: async () => ({
             isDirectory: () => false
         })
     };
@@ -113,12 +109,8 @@ test("find: findDirectories at depth=2", async () => {
 });
 
 test("find: findDirectories at depth=3", async () => {
-    const calls: string[] = [];
-
     const deps: FileSystemDependencies = {
         readdir: async (path: string): Promise<{ name: string; isDirectory(): boolean }[]> => {
-            calls.push(path);
-
             switch (path) {
                 case "/root":
                     return [dir("a"), dir("b")];
@@ -130,12 +122,12 @@ test("find: findDirectories at depth=3", async () => {
                 case "/root/b/b1":
                     return [dir("c")];
                 case "/root/b/b1/c":
-                    return [dir("d"), file("fd")]
+                    return [dir("d"), file("fd")];
                 default:
                     return [];
             }
         },
-        stat: async (_: string) => ({
+        stat: async () => ({
             isDirectory: () => false
         })
     };