tlc-claude-code 2.2.0 → 2.3.0

package/CODING-STANDARDS.md

@@ -241,25 +241,64 @@ if (status === 'pending') { ... }  // TypeScript will validate
 
 ---
 
-## 6. Configuration: No Hardcoded Values
+## 6. Configuration: Validated, Centralized, No Direct `process.env`
+
+### Centralized Config with Validation
+
+All configuration MUST go through a validated config module. Never read `process.env` directly in application code.
 
 ```typescript
-// ❌ NEVER
+// ❌ NEVER: Direct process.env in services/controllers
 class PaymentService {
-  private baseUrl = "https://api.stripe.com";
-  private timeout = 30000;
+  private baseUrl = process.env.STRIPE_BASE_URL || 'https://api.stripe.com';
+  private apiKey = process.env.STRIPE_API_KEY;  // silently undefined if missing
 }
 
-// ✅ ALWAYS
-// lib/configuration.ts or shared/config/stripe.config.ts
+// ❌ NEVER: Config without validation
 export const stripeConfig = {
   baseUrl: process.env.STRIPE_BASE_URL || 'https://api.stripe.com',
-  apiKey: process.env.STRIPE_API_KEY,
-  timeout: parseInt(process.env.STRIPE_TIMEOUT || '30000'),
-} as const;
+  apiKey: process.env.STRIPE_API_KEY,  // no validation, no fail-fast
+};
+
+// ✅ ALWAYS: Validated config module with fail-fast
+// src/config/config.ts
+import { z } from 'zod';
+
+const configSchema = z.object({
+  stripe: z.object({
+    baseUrl: z.string().url().default('https://api.stripe.com'),
+    apiKey: z.string().min(1, 'STRIPE_API_KEY is required'),
+    timeout: z.coerce.number().int().positive().default(30000),
+  }),
+});
+
+export type AppConfig = z.infer<typeof configSchema>;
+
+export function loadConfig(): AppConfig {
+  const result = configSchema.safeParse({
+    stripe: {
+      baseUrl: process.env.STRIPE_BASE_URL,
+      apiKey: process.env.STRIPE_API_KEY,
+      timeout: process.env.STRIPE_TIMEOUT,
+    },
+  });
+
+  if (!result.success) {
+    throw new Error(`Config validation failed:\n${result.error.format()}`);
+  }
+  return result.data;
+}
 ```
 
-**Rule**: If it could differ between environments, it's config.
+### Rules
+
+1. **All `process.env` access MUST be in the config module** — never in services, controllers, or middleware.
+2. **All required env vars MUST be validated at startup** — fail fast, not at first request.
+3. **Distinguish required vs optional** — required vars throw on boot; optional have explicit defaults.
+4. **No silent empty-string fallbacks** for secrets or connection strings.
+5. **Config is injected via DI or imported from the config module** — never read from env directly.
+
+**Rule**: If it could differ between environments, it's config. If it's required, validate it at boot.
 
 ---
 
@@ -432,6 +471,13 @@ Before committing any code:
 - [ ] Typed errors, not generic throws
 - [ ] Tests co-located with module
 - [ ] Build passes (`npm run build`)
+- [ ] **No direct `process.env`** in services/controllers — config module only
+- [ ] **Config validated at startup** with schema (Zod/Joi)
+- [ ] **Ownership checks** on every data-access endpoint
+- [ ] **No secrets in responses** — API keys, tokens are write-only
+- [ ] **Sensitive data hashed** at rest (OTPs, reset tokens)
+- [ ] **All HTML output escaped** — no raw interpolation of user values
+- [ ] **No manual `new Service()`** — use DI container
 
 ---
 
@@ -723,6 +769,160 @@ function handleResponse<T>(response: ApiResponse<T>): T {
 
 ---
 
+## 21. Security: Authorization, Secrets, and Output Encoding
+
+### Resource Ownership Checks
+
+Every endpoint that accesses a resource MUST verify the requesting user owns or has permission to access that resource. Authentication alone is not enough.
+
+```typescript
+// ❌ WRONG: Only checks authentication, not ownership
+@Get('settings/:merchantId')
+@UseGuards(AuthGuard)
+async getSettings(@Param('merchantId') merchantId: string): Promise<Settings> {
+  return this.settingsService.findByMerchant(merchantId); // any authed user can read any merchant
+}
+
+// ✅ CORRECT: Verifies ownership
+@Get('settings/:merchantId')
+@UseGuards(AuthGuard)
+async getSettings(
+  @Param('merchantId') merchantId: string,
+  @CurrentUser() user: User,
+): Promise<Settings> {
+  if (user.merchantId !== merchantId && user.role !== 'admin') {
+    throw new ForbiddenError('Cannot access another merchant\'s settings');
+  }
+  return this.settingsService.findByMerchant(merchantId);
+}
+```
+
+**Rules:**
+1. Every data-access endpoint MUST check that the requesting user owns the resource.
+2. Tests MUST prove that user A cannot read/modify user B's data.
+3. Prefer a reusable ownership guard over per-endpoint checks.
+
+### Never Expose Secrets in Responses
+
+API keys, webhook secrets, tokens, and credentials MUST never appear in API responses or rendered HTML.
+
+```typescript
+// ❌ WRONG: Returning secrets to the client
+return {
+  merchantId: merchant.id,
+  apiKey: merchant.apiKey,           // NEVER
+  webhookSecret: merchant.webhookSecret, // NEVER
+};
+
+// ✅ CORRECT: Mask or omit secrets
+return {
+  merchantId: merchant.id,
+  apiKey: mask(merchant.apiKey),     // "sk_live_...4x7f"
+  webhookSecret: '••••••••',         // write-only, never read back
+};
+```
+
+**Rules:**
+1. Secrets are **write-only** — accept on create/update, never return in GET responses.
+2. If display is needed, return masked values (first 4 + last 4 chars).
+3. Audit every response DTO and HTML template for leaked credentials.
+
+### Hash Sensitive Data at Rest
+
+OTP codes, reset tokens, and session secrets MUST be stored as one-way hashes, never plaintext.
+
+```typescript
+// ❌ WRONG: Plaintext OTP
+await db.otpSessions.insert({ code: '123456', expiresAt });
+
+// ✅ CORRECT: Hashed OTP
+import { createHash } from 'crypto';
+const hashedCode = createHash('sha256').update(code).digest('hex');
+await db.otpSessions.insert({ codeHash: hashedCode, expiresAt });
+
+// Verification: hash the input and compare
+function verifyOtp(input: string, stored: string): boolean {
+  const inputHash = createHash('sha256').update(input).digest('hex');
+  return timingSafeEqual(Buffer.from(inputHash), Buffer.from(stored));
+}
+```
+
+### Output Encoding (XSS Prevention)
+
+Never interpolate user-controlled values into HTML without escaping. This applies to inline HTML generation, template strings, and server-rendered pages.
+
+```typescript
+// ❌ WRONG: Raw interpolation — XSS risk
+const html = `<h1>Welcome, ${user.name}</h1>`;
+const html = `<a href="${redirectUrl}">Continue</a>`;
+
+// ✅ CORRECT: Always escape
+import { escapeHtml } from '@/shared/utils/escape';
+
+const html = `<h1>Welcome, ${escapeHtml(user.name)}</h1>`;
+const html = `<a href="${escapeHtml(redirectUrl)}">Continue</a>`;
+```
+
+```typescript
+// shared/utils/escape.ts
+/**
+ * Escapes HTML special characters to prevent XSS.
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+```
+
+**Rules:**
+1. **Every** dynamic value in HTML output MUST be escaped.
+2. Prefer a real templating engine over string concatenation for HTML.
+3. Audit merchant-controlled, query-string, and user-input values first.
+4. Do not add new pages using inline HTML string builders — use a proper frontend.
+
+---
+
+## 22. Dependency Injection: No Manual Instantiation
+
+Never manually instantiate services or providers that should be managed by the DI container.
+
+```typescript
+// ❌ WRONG: Bypassing DI
+class PaymentService {
+  async processPayment(method: string): Promise<void> {
+    const provider = method === 'cyberpay'
+      ? new CyberpayProvider(process.env.CYBERPAY_KEY)  // untestable, unmanaged
+      : new CodProvider();
+    await provider.charge(amount);
+  }
+}
+
+// ✅ CORRECT: Provider registry via DI
+@Injectable()
+class PaymentService {
+  constructor(
+    @Inject('PAYMENT_PROVIDERS') private providers: Map<string, PaymentProvider>,
+  ) {}
+
+  async processPayment(method: string): Promise<void> {
+    const provider = this.providers.get(method);
+    if (!provider) throw new BadRequestError(`Unknown payment method: ${method}`);
+    await provider.charge(amount);
+  }
+}
+```
+
+**Rules:**
+1. All providers/services MUST be registered in the DI container.
+2. Never use `new ServiceClass()` in application code — let the framework manage lifecycle.
+3. Use factory providers or provider registries for dynamic selection.
+
+---
+
 ## AI Instructions
 
 When generating code:
@@ -744,6 +944,13 @@ When generating code:
 15. **Never** let folders exceed 15 files - organize into subfolders
 16. **Never** use `any` type - use `unknown` or proper interfaces
 17. **Always** add explicit return types to functions
+18. **Never** read `process.env` outside the config module
+19. **Always** validate config at startup with a schema
+20. **Always** add ownership/authorization checks on data-access endpoints
+21. **Never** return secrets (API keys, tokens) in API responses or HTML
+22. **Always** hash OTPs, reset tokens, and session secrets before storing
+23. **Always** escape dynamic values in HTML output
+24. **Never** use `new ServiceClass()` — register in DI and inject
 
 ### Cleanup Tasks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",

package/server/lib/careful-patterns.js

@@ -0,0 +1,142 @@
+/**
+ * Careful Patterns Module
+ *
+ * Destructive command detection patterns for /tlc:careful
+ * and path scope checking for /tlc:freeze.
+ *
+ * @module careful-patterns
+ */
+
+const path = require('path');
+
+/**
+ * Destructive command patterns with their metadata.
+ * Each entry: { regex, reason, pattern }
+ * @type {Array<{regex: RegExp, reason: string, pattern: string}>}
+ */
+const DESTRUCTIVE_PATTERNS = [
+  {
+    regex: /\bgit\s+push\s+(?:.*\s+)?--force\b/,
+    reason: 'Force push',
+    pattern: 'git push --force',
+  },
+  {
+    regex: /\bgit\s+push\s+(?:.*\s+)?-f\b/,
+    reason: 'Force push',
+    pattern: 'git push -f',
+  },
+  {
+    regex: /\bgit\s+reset\s+--hard\b/,
+    reason: 'Hard reset',
+    pattern: 'git reset --hard',
+  },
+  {
+    regex: /\brm\s+-rf\b/,
+    reason: 'Recursive force delete',
+    pattern: 'rm -rf',
+  },
+  {
+    regex: /\bdrop\s+table\b/i,
+    reason: 'Drop table',
+    pattern: 'DROP TABLE',
+  },
+  {
+    regex: /\bdrop\s+database\b/i,
+    reason: 'Drop database',
+    pattern: 'DROP DATABASE',
+  },
+  {
+    regex: /\btruncate\s+table\b/i,
+    reason: 'Truncate table',
+    pattern: 'TRUNCATE TABLE',
+  },
+  {
+    regex: /\bgit\s+clean\s+-f/,
+    reason: 'Clean untracked files',
+    pattern: 'git clean -f',
+  },
+];
+
+/**
+ * Check if a shell command matches destructive patterns.
+ *
+ * Checks against known dangerous operations like force push,
+ * hard reset, recursive delete, and destructive SQL statements.
+ * SQL patterns are matched case-insensitively.
+ *
+ * @param {string} command - Shell command string to check
+ * @returns {{ destructive: boolean, reason?: string, pattern?: string }}
+ */
+function isDestructive(command) {
+  if (!command || typeof command !== 'string') {
+    return { destructive: false };
+  }
+
+  // Check DELETE FROM without WHERE (special case: only destructive without WHERE)
+  // Don't early-return on safe DELETE — continue checking for other destructive patterns
+  const deleteMatch = command.match(/\bdelete\s+from\b/i);
+  if (deleteMatch) {
+    const hasWhere = /\bwhere\b/i.test(command);
+    if (!hasWhere) {
+      return {
+        destructive: true,
+        reason: 'Delete without WHERE',
+        pattern: 'DELETE FROM',
+      };
+    }
+    // DELETE FROM ... WHERE is safe, but continue scanning for other patterns
+    // (e.g., "DELETE FROM users WHERE id=1; DROP TABLE sessions")
+  }
+
+  // Check all other patterns
+  for (const entry of DESTRUCTIVE_PATTERNS) {
+    if (entry.regex.test(command)) {
+      return {
+        destructive: true,
+        reason: entry.reason,
+        pattern: entry.pattern,
+      };
+    }
+  }
+
+  return { destructive: false };
+}
+
+/**
+ * Check if a file path is within an allowed scope directory.
+ *
+ * Resolves parent traversal (../) before checking containment.
+ * Both paths are normalized to prevent bypass via trailing slashes
+ * or prefix collisions (e.g., src/auth vs src/authorization).
+ *
+ * @param {string} filePath - File path to check
+ * @param {string} scopeDir - Allowed scope directory
+ * @returns {boolean}
+ */
+function isInScope(filePath, scopeDir) {
+  if (!filePath || !scopeDir) {
+    return false;
+  }
+  if (typeof filePath !== 'string' || typeof scopeDir !== 'string') {
+    return false;
+  }
+
+  // Normalize both paths to resolve ../ and remove trailing slashes
+  const normalizedFile = path.normalize(filePath);
+  const normalizedScope = path.normalize(scopeDir);
+
+  // Exact match
+  if (normalizedFile === normalizedScope) {
+    return true;
+  }
+
+  // File must be under scope directory (with path separator to prevent prefix collisions)
+  const scopePrefix = normalizedScope.endsWith(path.sep)
+    ? normalizedScope
+    : normalizedScope + path.sep;
+
+  return normalizedFile.startsWith(scopePrefix);
+}
+
+
+module.exports = { isDestructive, isInScope };

package/server/lib/careful-patterns.test.js

@@ -0,0 +1,164 @@
+/**
+ * Careful Patterns Tests - Phase 89 Task 6
+ *
+ * Destructive command detection and path scope checking
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { isDestructive, isInScope } from './careful-patterns.js';
+
+describe('careful-patterns', () => {
+  describe('isDestructive', () => {
+    it('detects git push --force as destructive', () => {
+      const result = isDestructive('git push --force origin main');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Force push');
+      expect(result.pattern).toBe('git push --force');
+    });
+
+    it('detects git push -f as destructive', () => {
+      const result = isDestructive('git push -f origin main');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Force push');
+    });
+
+    it('allows normal git push', () => {
+      const result = isDestructive('git push origin feature');
+      expect(result.destructive).toBe(false);
+      expect(result.reason).toBeUndefined();
+      expect(result.pattern).toBeUndefined();
+    });
+
+    it('detects git reset --hard as destructive', () => {
+      const result = isDestructive('git reset --hard HEAD~3');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Hard reset');
+      expect(result.pattern).toBe('git reset --hard');
+    });
+
+    it('allows git reset --soft', () => {
+      const result = isDestructive('git reset --soft HEAD~1');
+      expect(result.destructive).toBe(false);
+    });
+
+    it('detects rm -rf as destructive', () => {
+      const result = isDestructive('rm -rf /');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Recursive force delete');
+      expect(result.pattern).toBe('rm -rf');
+    });
+
+    it('allows simple rm', () => {
+      const result = isDestructive('rm file.txt');
+      expect(result.destructive).toBe(false);
+    });
+
+    it('detects DROP TABLE as destructive', () => {
+      const result = isDestructive('DROP TABLE users');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Drop table');
+      expect(result.pattern).toMatch(/drop table/i);
+    });
+
+    it('detects DELETE FROM without WHERE as destructive', () => {
+      const result = isDestructive('DELETE FROM users');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Delete without WHERE');
+    });
+
+    it('allows DELETE FROM with WHERE', () => {
+      const result = isDestructive('DELETE FROM users WHERE id = 1');
+      expect(result.destructive).toBe(false);
+    });
+
+    it('detects DROP after safe DELETE in multi-statement command', () => {
+      const result = isDestructive('DELETE FROM users WHERE id = 1; DROP TABLE sessions');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Drop table');
+    });
+
+    it('detects TRUNCATE TABLE as destructive', () => {
+      const result = isDestructive('TRUNCATE TABLE sessions');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Truncate table');
+    });
+
+    it('detects git clean -fd as destructive', () => {
+      const result = isDestructive('git clean -fd');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Clean untracked files');
+      expect(result.pattern).toBe('git clean -f');
+    });
+
+    it('allows npm install', () => {
+      const result = isDestructive('npm install express');
+      expect(result.destructive).toBe(false);
+    });
+
+    it('detects DROP DATABASE as destructive', () => {
+      const result = isDestructive('DROP DATABASE production');
+      expect(result.destructive).toBe(true);
+      expect(result.reason).toBe('Drop database');
+    });
+
+    it('handles SQL commands case-insensitively', () => {
+      expect(isDestructive('drop table users').destructive).toBe(true);
+      expect(isDestructive('Drop Table users').destructive).toBe(true);
+      expect(isDestructive('DELETE from users').destructive).toBe(true);
+      expect(isDestructive('truncate TABLE sessions').destructive).toBe(true);
+    });
+
+    it('returns destructive:false for empty string', () => {
+      const result = isDestructive('');
+      expect(result.destructive).toBe(false);
+    });
+
+    it('returns destructive:false for null/undefined', () => {
+      expect(isDestructive(null).destructive).toBe(false);
+      expect(isDestructive(undefined).destructive).toBe(false);
+    });
+  });
+
+  describe('isInScope', () => {
+    it('returns true for file within scope directory', () => {
+      expect(isInScope('src/auth/login.ts', 'src/auth')).toBe(true);
+    });
+
+    it('returns false for file outside scope directory', () => {
+      expect(isInScope('src/user/user.ts', 'src/auth')).toBe(false);
+    });
+
+    it('returns false for parent traversal attempts', () => {
+      expect(isInScope('src/auth/../user/user.ts', 'src/auth')).toBe(false);
+    });
+
+    it('returns true for deeply nested files within scope', () => {
+      expect(isInScope('src/auth/deep/nested/file.ts', 'src/auth')).toBe(true);
+    });
+
+    it('returns true for exact directory match', () => {
+      expect(isInScope('src/auth', 'src/auth')).toBe(true);
+    });
+
+    it('returns false when file path starts with scope but is a different dir', () => {
+      // src/authorization is not inside src/auth
+      expect(isInScope('src/authorization/file.ts', 'src/auth')).toBe(false);
+    });
+
+    it('handles trailing slashes consistently', () => {
+      expect(isInScope('src/auth/file.ts', 'src/auth/')).toBe(true);
+      expect(isInScope('src/auth/file.ts', 'src/auth')).toBe(true);
+    });
+
+    it('returns false for empty inputs', () => {
+      expect(isInScope('', 'src/auth')).toBe(false);
+      expect(isInScope('src/auth/file.ts', '')).toBe(false);
+    });
+
+    it('returns false for null/undefined inputs', () => {
+      expect(isInScope(null, 'src/auth')).toBe(false);
+      expect(isInScope('src/auth/file.ts', null)).toBe(false);
+    });
+  });
+});

package/server/lib/field-report.js

@@ -0,0 +1,92 @@
+/**
+ * Field Report Module — Agent Self-Rating
+ *
+ * After build/review, the agent rates its experience and files structured
+ * reports when quality falls below threshold (rating < 8).
+ */
+
+/** Rating threshold — reports are filed when rating is below this value */
+const REPORT_THRESHOLD = 8;
+
+/**
+ * Determine whether a field report should be filed based on the rating.
+ * @param {number} rating - Self-assessed quality rating (0–10)
+ * @returns {boolean} true if rating < 8, false otherwise
+ */
+function shouldFileReport(rating) {
+  if (typeof rating !== 'number') {
+    throw new TypeError('rating must be a number');
+  }
+  return rating < REPORT_THRESHOLD;
+}
+
+/**
+ * Create a formatted field report from the given parameters.
+ * @param {object} params
+ * @param {string} params.skill - The TLC skill that was executed (e.g. 'tlc:build')
+ * @param {number} params.rating - Self-assessed quality rating (0–10)
+ * @param {string} params.issue - Description of the issue encountered
+ * @param {string} params.suggestion - Suggested improvement
+ * @param {() => Date} [params.now] - Optional clock function for deterministic dates
+ * @returns {string} Formatted markdown report
+ */
+function createFieldReport({ skill, rating, issue, suggestion, now }) {
+  if (!skill) {
+    throw new Error('skill is required');
+  }
+  if (typeof rating !== 'number') {
+    throw new TypeError('rating must be a number');
+  }
+  if (!issue) {
+    throw new Error('issue is required');
+  }
+  if (!suggestion) {
+    throw new Error('suggestion is required');
+  }
+
+  const date = (now ? now() : new Date()).toISOString();
+  const critical = rating === 0 ? ' CRITICAL' : '';
+  const heading = `## ${date} ${skill} ${rating}/10${critical} — ${issue}`;
+  const body = `**Suggestion:** ${suggestion}`;
+
+  return `${heading}\n\n${body}\n`;
+}
+
+/**
+ * Format a report string as a single markdown section.
+ * Ensures the entry ends with exactly one trailing newline.
+ * @param {string} report - Raw report content from createFieldReport
+ * @returns {string} Formatted markdown section with trailing newline
+ */
+function formatReportEntry(report) {
+  if (typeof report !== 'string') {
+    throw new TypeError('report must be a string');
+  }
+  return report.trimEnd() + '\n';
+}
+
+/**
+ * Append a new report to existing file content.
+ * If existing content is empty, creates a new document with a header.
+ * @param {string} existingContent - Current file content (may be empty)
+ * @param {string} newReport - New report to append
+ * @returns {string} Combined content
+ */
+function appendReport(existingContent, newReport) {
+  if (typeof existingContent !== 'string') {
+    throw new TypeError('existingContent must be a string');
+  }
+  if (typeof newReport !== 'string') {
+    throw new TypeError('newReport must be a string');
+  }
+
+  const entry = formatReportEntry(newReport);
+
+  if (!existingContent) {
+    return `# Field Reports\n\n${entry}`;
+  }
+
+  return `${existingContent}\n\n---\n\n${entry}`;
+}
+
+module.exports = { shouldFileReport, createFieldReport, formatReportEntry, appendReport };