tlc-claude-code 2.2.1 → 2.4.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