@devshub198211/devguard 2.0.1 → 2.0.3

package/MODULES.md

@@ -0,0 +1,281 @@
+# DevGuard Modules Reference
+
+All 14 modules explained with examples.
+
+---
+
+## Security Modules
+
+### 1. lockfile-guardian
+**What:** Detects tampering in `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` using SHA-512 hashing.
+
+```typescript
+import { verifyLockfile, createSnapshot } from '@devshub198211/devguard/security';
+
+// Create a trusted baseline after clean install
+createSnapshot();
+
+// Later, verify nothing has changed
+const result = verifyLockfile();
+if (!result.valid) console.log('Tampered files:', result.tampered);
+```
+
+```bash
+devguard snapshot   # Create baseline
+devguard check      # Verify integrity
+```
+
+---
+
+### 2. hook-scanner
+**What:** Scans `node_modules` for 23+ malicious patterns in install scripts (obfuscation, network exfiltration, shell commands).
+
+```typescript
+import { scanProject } from '@devshub198211/devguard/security';
+
+const findings = scanProject();
+findings.forEach(f => console.log(`${f.package}: ${f.pattern} [${f.severity}]`));
+```
+
+```bash
+devguard scan
+```
+
+---
+
+### 3. token-rotator
+**What:** Checks API token age and verifies tokens are still valid via live API calls (opt-in).
+
+```typescript
+import { checkTokenAge, loadTokensFromEnv } from '@devshub198211/devguard/security';
+
+const tokens = loadTokensFromEnv(['NPM_TOKEN', 'GITHUB_TOKEN']);
+const alerts = checkTokenAge(tokens);
+alerts.filter(a => a.status === 'stale').forEach(a => console.log(`Rotate: ${a.name}`));
+```
+
+```bash
+devguard tokens
+```
+
+---
+
+### 4. dep-pincer
+**What:** Finds dependencies using ranges (`^1.0.0`) and pins them to exact versions. Generates SRI hashes.
+
+```typescript
+import { autoPin } from '@devshub198211/devguard/security';
+
+const result = autoPin('.', true); // true = auto-fix
+console.log(`Pinned ${result.fixed} dependencies`);
+```
+
+```bash
+devguard pin --fix
+```
+
+---
+
+## AI & Code Modules
+
+### 5. refactor-engine
+**What:** Analyzes code for complexity (O(n) vs O(n²)), security flaws (eval, innerHTML), and structural issues. Opens a browser-based diff reviewer.
+
+```bash
+devguard refactor src/utils.ts
+```
+
+Detects and fixes:
+- `eval()` → `JSON.parse()` (security)
+- `.innerHTML` → `.textContent` (XSS prevention)
+- `var` → `const` (modern JS)
+- Deep nesting → guard clauses (readability)
+- Missing try/catch in async functions (error safety)
+
+---
+
+### 6. agent-schema
+**What:** Type-safe schema builder for validating LLM JSON output with auto-retry and structural repair.
+
+```typescript
+import { c, parseWithRetry } from '@devshub198211/devguard/ai';
+
+const TaskSchema = c.object({
+  title:    c.string().min(1),
+  priority: c.string().enum(['high', 'medium', 'low']),
+});
+
+const result = await parseWithRetry(TaskSchema, async (ctx) => {
+  return await callYourLLM(ctx);
+});
+// result.data is fully typed: { title: string; priority: 'high'|'medium'|'low' }
+```
+
+---
+
+### 7. mcp-server-kit
+**What:** Build Model Context Protocol servers that work with Claude Desktop and other MCP clients.
+
+```typescript
+import { MCPServerBuilder } from '@devshub198211/devguard/ai';
+
+new MCPServerBuilder('my-tools', '1.0.0')
+  .addTool({
+    name: 'get_weather',
+    description: 'Get weather for a city',
+    inputSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+    handler: async ({ city }) => ({ temp: '22°C', city })
+  })
+  .startStdio();
+```
+
+```bash
+devguard mcp
+```
+
+---
+
+### 8. agent-memory
+**What:** Persistent state storage for AI agents. Supports FileSystem and in-memory adapters.
+
+```typescript
+import { FileSystemAdapter } from '@devshub198211/devguard/ai';
+
+const memory = new FileSystemAdapter('.agent-data');
+await memory.save('agent-1', {
+  id: '1', role: 'user', content: 'Hello', timestamp: Date.now()
+});
+const history = await memory.getHistory('agent-1', 10);
+```
+
+---
+
+### 9. llm-budget
+**What:** Track token usage and spending across OpenAI, Anthropic, Google, and other LLM providers.
+
+```typescript
+import { LLMBudget } from '@devshub198211/devguard/ai';
+
+const budget = new LLMBudget({ monthlyLimitUSD: 50, warnAtUSD: 40 });
+budget.track({
+  model: 'gpt-4o', provider: 'openai',
+  tokensPrompt: 1000, tokensCompletion: 500, costUSD: 0.015
+});
+console.log(budget.report()); // { totalCost, isOverBudget, ... }
+```
+
+---
+
+## Auth Modules
+
+### 10. zero-trust-jwt
+**What:** JWT verification with HS256/RS256/JWKS support, revocation lists, and anomaly detection.
+
+```typescript
+import { JWTVerifier } from '@devshub198211/devguard/auth';
+
+const verifier = new JWTVerifier({ secret: process.env.JWT_SECRET });
+const { valid, payload, anomalies } = await verifier.verify(token);
+// anomalies: { score: 0, level: 'safe', warnings: [] }
+```
+
+```bash
+devguard jwt-verify --token <jwt> --secret <key>
+```
+
+---
+
+### 11. bot-fence
+**What:** Multi-signal bot detection for Express/Fastify middleware. Checks IP, headers, rate limits.
+
+```typescript
+import { createMiddleware, IPRateLimiter } from '@devshub198211/devguard/auth';
+
+app.use(createMiddleware({
+  blockThreshold: 70,
+  rateLimiter: new IPRateLimiter(100, 60_000)
+}));
+```
+
+```bash
+devguard bot-check
+```
+
+---
+
+### 12. passkey-node
+**What:** Complete WebAuthn/Passkey implementation using only Node.js crypto. Supports ES256 and RS256.
+
+```typescript
+import {
+  generateRegistrationOptions,
+  verifyRegistration,
+  generateAuthenticationOptions,
+  verifyAuthentication
+} from '@devshub198211/devguard/auth';
+
+const options = generateRegistrationOptions({
+  rpId: 'example.com', rpName: 'My App',
+  userId: 'user-1', userName: 'alice'
+});
+```
+
+---
+
+## DX Modules
+
+### 13. env-safe
+**What:** Validates `.env` files against a typed schema at startup. Fails fast with clear error messages.
+
+```typescript
+import { loadEnv } from '@devshub198211/devguard/dx';
+
+const env = loadEnv({
+  DATABASE_URL: { type: 'url',     required: true },
+  PORT:         { type: 'integer', default: '3000', min: 1, max: 65535 },
+  NODE_ENV:     { type: 'string',  enum: ['development', 'production', 'test'] },
+});
+// Throws immediately if any variable is missing or invalid
+```
+
+---
+
+### 14. log-otlp
+**What:** Structured JSON logger compatible with OpenTelemetry. Supports child loggers and trace injection.
+
+```typescript
+import { createLogger } from '@devshub198211/devguard/dx';
+
+const log = createLogger({ service: 'api', level: 'info' });
+log.info('Request received', { userId: 'u-123', path: '/orders' });
+log.error('Payment failed', { orderId: 'o-456', reason: 'declined' });
+
+const reqLog = log.child({ requestId: 'req-789' });
+reqLog.info('Processing');
+```
+
+---
+
+### Bonus: api-contract
+**What:** Zero-dependency schema builder with full TypeScript type inference for API validation.
+
+```typescript
+import { c, validateBody } from '@devshub198211/devguard/dx';
+
+const UserSchema = c.object({
+  name:  c.string().min(1).max(100),
+  email: c.string(),
+  age:   c.number().min(0).max(150).optional(),
+});
+
+// Express middleware
+app.post('/users', validateBody(UserSchema), (req, res) => {
+  // req.body is fully typed
+});
+```
+
+---
+
+*Your custom notes below:*
+
+<!-- Add your personal notes, contact info, or acknowledgments here -->

package/README.md

@@ -1,167 +1,151 @@
-# devguard
+# @devshub198211/devguard
 
-> **One install. 14 features. Zero external dependencies.**  
-> Security · AI Tooling · Auth · DX — everything a production Node.js/TypeScript project needs.
+> **One install. 14 modules. Zero external dependencies.**
+> Security · AI Tooling · Auth · DX — everything a production Node.js project needs.
 
 ```bash
-npm install devguard
-npx devguard        # instant security scan — no install needed
+npm install @devshub198211/devguard
 ```
 
-[![npm](https://img.shields.io/npm/v/devguard)](https://www.npmjs.com/package/devguard)
-[![license](https://img.shields.io/npm/l/devguard)](LICENSE)
-[![node](https://img.shields.io/node/v/devguard)](package.json)
-
----
-
-## Features
-
-| Category | Feature | What it does |
-|----------|---------|-------------|
-| 🔒 Security | `lockfile-guardian` | SHA-512 tamper detection for npm/yarn/pnpm lockfiles |
-| 🔒 Security | `hook-scanner` | 23-rule malware scanner for install scripts (obfuscation-aware) |
-| 🔒 Security | `token-rotator` | Live API verification + age alerts for npm/GitHub tokens |
-| 🔒 Security | `dep-pincer` | Enforce exact version pins + SRI hash verification |
-| 🤖 AI | `agent-schema` | Validate LLM JSON output, auto-retry on malformed responses |
-| 🤖 AI | `mcp-server-kit` | Build Claude-compatible MCP tool servers in minutes |
-| 🤖 AI | `agent-memory` | Durable agent state: Memory / FileSystem / Redis / DynamoDB |
-| 🤖 AI | `llm-budget` | Token counting + cost tracking for OpenAI/Anthropic/Gemini |
-| 🔑 Auth | `zero-trust-jwt` | JWT verify (HS256/RS256/JWKS), revocation, anomaly detection |
-| 🔑 Auth | `bot-fence` | Multi-signal bot detection middleware for Express/Fastify |
-| 🔑 Auth | `passkey-node` | Production WebAuthn passkey registration & authentication |
-| 🛠 DX | `env-safe` | Typed .env validation with built-in parser — fail fast |
-| 🛠 DX | `log-otlp` | Structured JSON logger with OpenTelemetry trace injection |
-| 🛠 DX | `api-contract` | Zero-dep schema builder with full TypeScript type inference |
-
 ---
 
 ## Quick Start
 
-### CLI
 ```bash
-npx devguard                    # full security scan + score
-npx devguard lockfile snapshot  # create baseline after clean install
-npx devguard lockfile verify    # check integrity
-npx devguard hooks              # scan node_modules for malware
-npx devguard pins --fix         # auto-pin unpinned dependencies
-npx devguard tokens --live      # verify tokens via API
-npx devguard --json             # machine-readable output for CI
-```
+# Initialize DevGuard in your project
+npx @devshub198211/devguard init
 
-### Programmatic
-```typescript
-import { runAllChecks } from 'devguard';
+# Run a full security audit
+npx @devshub198211/devguard check
 
-const report = await runAllChecks();
-// { score: 94, passedAll: true, lockfile: {...}, hooks: {...}, ... }
-if (!report.passedAll) process.exit(1);
+# AI-powered code refactor (free, runs locally)
+npx @devshub198211/devguard refactor src/app.ts
 ```
 
-### Tree-shakeable sub-path imports
-```typescript
-import { verifyLockfile } from 'devguard/security';
-import { LLMBudget }      from 'devguard/ai';
-import { JWTVerifier }    from 'devguard/auth';
-import { loadEnv }        from 'devguard/dx';
+For global CLI access:
+```bash
+npm install -g @devshub198211/devguard
+devguard check
 ```
 
 ---
 
-## Examples
+## All 14 Modules
+
+| # | Category | Module | CLI Command | What It Does |
+|---|----------|--------|-------------|--------------|
+| 1 | 🔒 Security | `lockfile-guardian` | `check` / `snapshot` | SHA-512 lockfile tamper detection |
+| 2 | 🔒 Security | `hook-scanner` | `scan` | 23-rule malware scanner for install scripts |
+| 3 | 🔒 Security | `token-rotator` | `tokens` | Live API token verification + age alerts |
+| 4 | 🔒 Security | `dep-pincer` | `pin --fix` | Enforce exact version pins + SRI hashes |
+| 5 | 🤖 AI | `refactor-engine` | `refactor <file>` | Complexity analysis + security patching |
+| 6 | 🤖 AI | `agent-schema` | `schema <json>` | Validate & auto-repair LLM JSON output |
+| 7 | 🤖 AI | `mcp-server-kit` | `mcp` | Build Claude-compatible MCP tool servers |
+| 8 | 🤖 AI | `agent-memory` | `memory --agent <id>` | Durable state for AI agents (FS/Redis) |
+| 9 | 🤖 AI | `llm-budget` | `budget` | Token counting + cost tracking |
+| 10 | 🔑 Auth | `zero-trust-jwt` | `jwt-verify` / `jwt-sign` | JWT sign & verify with anomaly detection |
+| 11 | 🔑 Auth | `bot-fence` | `bot-check --ip <ip>` | Multi-signal bot detection middleware |
+| 12 | 🔑 Auth | `passkey-node` | `passkey-verify` | WebAuthn passkey registration & auth |
+| 13 | 🛠 DX | `env-safe` | `env-verify` | Typed .env validation — fail fast |
+| 14 | 🛠 DX | `log-otlp` | `log --msg <text>` | Structured JSON logger + OpenTelemetry |
+
+**Bonus:** `api-contract` — zero-dep schema builder with TypeScript inference.
 
-### Security — run all checks
-```typescript
-import { runAllChecks } from 'devguard';
-const report = await runAllChecks();
-console.log(`Security score: ${report.score}/100`);
-```
+---
 
-### AI — validate LLM output
-```typescript
-import { c, parseWithRetry } from 'devguard';
-
-const TaskSchema = c.object({
-  title:    c.string().min(1),
-  priority: c.string().enum(["high","medium","low"]),
-  dueDate:  c.string().optional(),
-});
-
-const result = await parseWithRetry(TaskSchema, async (ctx) => {
-  return await callYourLLM(ctx); // your LLM call here
-});
-// result.data is fully typed: { title: string; priority: "high"|"medium"|"low"; dueDate?: string }
-```
+## Use From Any Language (Python, Go, Bash, etc.)
 
-### AI — agent with durable memory
-```typescript
-import { createMemory } from 'devguard';
+Every command supports `--json` output, making DevGuard usable from **any programming language**:
+
+### Python
+```python
+import subprocess, json
 
-// Persists across serverless invocations
-const memory = createMemory({ agentId: 'agent-001', adapter: 'fs', ttl: 7200 });
-await memory.setState({ step: 3, context: 'processing order' });
-await memory.appendHistory('user', 'Cancel my order');
-const history = await memory.getHistory(10); // last 10 messages
+result = subprocess.run(
+    ["npx", "@devshub198211/devguard", "check", "--json"],
+    capture_output=True, text=True
+)
+report = json.loads(result.stdout)
+print(f"Security Score: {report['score']}/100")
 ```
 
-### AI — build an MCP tool server
-```typescript
-import { MCPServerBuilder } from 'devguard';
-
-new MCPServerBuilder('my-tools', '1.0.0')
-  .addTool({
-    name: 'get_weather',
-    description: 'Get weather for a city',
-    inputSchema: { type:'object', properties:{ city:{type:'string'} }, required:['city'] },
-    handler: async ({ city }) => ({ temp: '22°C', city })
-  })
-  .startStdio(); // works with Claude Desktop + any MCP client
+### Go
+```go
+cmd := exec.Command("npx", "@devshub198211/devguard", "scan", "--json")
+output, _ := cmd.Output()
+// Parse JSON output
 ```
 
-### Auth — JWT verification
-```typescript
-import { JWTVerifier } from 'devguard';
+### Bash
+```bash
+SCORE=$(npx @devshub198211/devguard check --json | jq '.score')
+echo "Score: $SCORE"
 
-const verifier = new JWTVerifier({ secret: process.env.JWT_SECRET! });
-const { valid, payload, anomalies } = await verifier.verify(token);
-// anomalies: { score: 0, level: 'safe', warnings: [] }
+# Sign a JWT
+TOKEN=$(devguard jwt-sign --payload '{"sub":"user-1"}' --secret mykey --json | jq -r '.token')
+
+# Check an IP
+devguard bot-check --ip 203.0.113.5 --json | jq '.verdict'
 ```
 
-### Auth — bot detection middleware
-```typescript
-import express from 'express';
-import { createMiddleware, IPRateLimiter } from 'devguard';
-
-const app = express();
-app.use(createMiddleware({
-  blockThreshold: 70,
-  rateLimiter: new IPRateLimiter(100, 60_000)
-}));
+### Ruby
+```ruby
+result = `npx @devshub198211/devguard check --json`
+report = JSON.parse(result)
+puts "Score: #{report['score']}"
 ```
 
-### DX — typed .env validation
-```typescript
-import { loadEnv } from 'devguard';
-
-const env = loadEnv({
-  DATABASE_URL: { type: 'url',     required: true },
-  PORT:         { type: 'integer', default: '3000', min: 1, max: 65535 },
-  NODE_ENV:     { type: 'string',  enum: ['development','production','test'] },
-  API_KEY:      { type: 'string',  required: true, minLength: 32, secret: true },
-});
-// Throws with clear message if invalid. env.PORT is typed as number.
+---
+
+## CLI Reference
+
+```bash
+# Core
+devguard init                                    # Set up project
+devguard check [--json]                          # Full security audit
+devguard refactor <file> [--json]                # AI code refactor
+devguard mcp                                     # Start MCP server
+
+# Security
+devguard snapshot                                # Create lockfile baseline
+devguard scan [--json]                           # Malware scan
+devguard tokens [--json]                         # Token health check
+devguard pin [--fix] [--json]                    # Pin dependencies
+
+# AI
+devguard schema '<json>' [--json]                # Validate JSON
+devguard memory [--agent <id>] [--json]          # Query agent state
+devguard budget [--json]                         # LLM cost summary
+
+# Auth
+devguard jwt-verify --token <t> --secret <s>     # Verify JWT
+devguard jwt-sign --payload '<json>' --secret <s> # Sign JWT
+devguard bot-check --ip <ip> [--json]            # Bot detection
+
+# DX
+devguard env-verify [--file .env] [--json]       # Validate env
+devguard log --msg <text> [--level info|warn|error]  # Emit log
 ```
 
-### DX — structured logging
+---
+
+## Programmatic Usage (Node.js / TypeScript)
+
 ```typescript
-import { createLogger } from 'devguard';
+import { runAllChecks } from '@devshub198211/devguard';
 
-const log = createLogger({ service: 'api', level: 'info' });
-log.info('Request received', { userId: 'u-123', path: '/orders' });
-log.error('Payment failed', { orderId: 'o-456', reason: 'declined' });
+const report = await runAllChecks();
+console.log(`Security Score: ${report.score}/100`);
+if (!report.passedAll) process.exit(1);
+```
+
+### Tree-Shakeable Sub-Path Imports
 
-// Child logger inherits bindings
-const reqLog = log.child({ requestId: 'req-789' });
-reqLog.info('Processing');
+```typescript
+import { verifyLockfile } from '@devshub198211/devguard/security';
+import { LLMBudget }      from '@devshub198211/devguard/ai';
+import { JWTVerifier }    from '@devshub198211/devguard/auth';
+import { loadEnv }        from '@devshub198211/devguard/dx';
 ```
 
 ---
@@ -179,29 +163,36 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: '20' }
       - run: npm ci
-      - run: npx devguard --json > devguard-report.json
-        env:
-          DEVGUARD_TOKENS: NPM_TOKEN,GITHUB_TOKEN
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - uses: actions/upload-artifact@v4
-        with: { name: security-report, path: devguard-report.json }
-      - run: node -e "const r=require('./devguard-report.json'); if(!r.passedAll) process.exit(1)"
+      - run: npx @devshub198211/devguard check --json > report.json
+      - run: node -e "const r=JSON.parse(require('fs').readFileSync('report.json'));if(!r.passedAll)process.exit(1)"
 ```
 
 ---
 
-## Security
+## Security Guarantees
 
 - ✅ **Zero external runtime dependencies** — only Node.js built-ins
-- ✅ **No network calls** at runtime except token inspection (opt-in)
+- ✅ **No network calls** at runtime (except opt-in token verification)
 - ✅ **No telemetry, no tracking, no phone-home**
-- ✅ **Constant-time JWT comparison** — prevents timing attacks
+- ✅ **Constant-time JWT comparison** — timing attack protection
 - ✅ **Sign-count replay protection** in WebAuthn
+- ✅ **Path traversal protection** — all file IDs are SHA-256 hashed
+- ✅ **Prototype pollution prevention** in CBOR/JSON parsers
+- ✅ **Atomic file writes** — no data corruption during crashes
 - ✅ **Works fully offline** — all security checks are local
 
 ---
 
+## Requirements
+
+- Node.js >= 18.0.0
+
 ## License
 
 MIT © DevGuard Contributors
+
+---
+
+*Your custom notes below:*
+
+<!-- Add your personal notes, contact info, or acknowledgments here -->