@synergyerp/backend-standards 1.4.0 → 1.5.0

package/.husky/pre-commit

@@ -4,5 +4,8 @@
 # Detect --no-verify bypass patterns
 sh "$(dirname -- "$0")/../scripts/detect-no-verify.sh"
 
+echo "🔐 Running security check..."
+pnpm check-security
+
 echo "🔍 Running lint-staged..."
 pnpm exec lint-staged

package/.husky/pre-push

@@ -5,4 +5,4 @@
 sh "$(dirname -- "$0")/../scripts/detect-no-verify.sh"
 
 echo "🚀 Running pre-push quality checks..."
-pnpm lint && pnpm check-modularization && pnpm check-types && pnpm test:ci
+pnpm lint && pnpm check-security && pnpm check-modularization && pnpm check-types && pnpm test:ci

package/BACKEND_STANDARDS.md

@@ -630,6 +630,33 @@ app.use(
 );
 ```
 
+### 10.7 Automated Security Enforcement
+
+Security standards are enforced automatically by the `check-security` hook (`scripts/check-security.mjs`). The hook scans the consuming project's `src/` directory and fails if any of the following are detected:
+
+| Rule                       | What is checked                                                                                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **No raw SQL**             | `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER` inside template literals (allowed in `.sql` files and `migrations/` / `seeds/` directories).                            |
+| **No hardcoded secrets**   | `api_key`, `password`, `secret`, `token` (and common variants) assigned to string literals. Environment variable references (`process.env.*`, `import.meta.env.*`) are allowed. |
+| **Response masking**       | At least one source file must contain `[REDACTED]` or a `mask()` / `maskSensitive()` function.                                                                                  |
+| **Rate limiting**          | At least one source file must use `express-rate-limit` or a `rateLimit()` call.                                                                                                 |
+| **Helmet**                 | At least one source file must call `helmet()`.                                                                                                                                  |
+| **CORS whitelist**         | `origin: '*'` or `cors()` without a whitelist is blocked.                                                                                                                       |
+| **Input validation**       | At least one source file must use `zod`, `class-validator`, or `joi`.                                                                                                           |
+| **No exposed auth tokens** | Responses must not return `token`, `authorization`, `accessToken`, `refreshToken`, `api_key`, or `secret` fields in the response body.                                          |
+
+Add the script to the consuming project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "check-security": "node scripts/check-security.mjs"
+  }
+}
+```
+
+The `backend-standards` package also exposes a binary (`check-backend-security`) so consuming projects can run it via `npx` / `pnpm exec`.
+
 ---
 
 ## 11. Enforcement: Husky, Git Hooks & CI/CD Validation
@@ -638,18 +665,18 @@ app.use(
 
 Every standard must be machine-enforced to be effective.
 
-| Layer           | Tool                | When         | Purpose                        |
-| --------------- | ------------------- | ------------ | ------------------------------ |
-| L1: Editor      | ESLint + Prettier   | Every save   | Immediate developer feedback   |
-| L2: Pre-commit  | Husky + lint-staged | Every commit | Block bad code locally         |
-| L3: CI Pipeline | GitHub Actions      | Every PR     | Enforce standards before merge |
-| L4: CD Pipeline | Smoke Tests         | Every deploy | Verify runtime integrity       |
+| Layer           | Tool                                   | When         | Purpose                                      |
+| --------------- | -------------------------------------- | ------------ | -------------------------------------------- |
+| L1: Editor      | ESLint + Prettier                      | Every save   | Immediate developer feedback                 |
+| L2: Pre-commit  | Husky + `check-security` + lint-staged | Every commit | Block bad code & security violations locally |
+| L3: CI Pipeline | GitHub Actions                         | Every PR     | Enforce standards before merge               |
+| L4: CD Pipeline | Smoke Tests                            | Every deploy | Verify runtime integrity                     |
 
 ### 11.2 Required Git Hooks (Husky)
 
-- **pre-commit**: Runs `lint-staged` (ESLint + Prettier).
+- **pre-commit**: Runs `check-security` then `lint-staged` (ESLint + Prettier).
 - **commit-msg**: Validates commit messages using `commitlint`.
-- **pre-push**: Runs linting, full test suite, type checking, **and modularization validation**.
+- **pre-push**: Runs linting, `check-security`, full test suite, type checking, **and modularization validation**.
 
 ### 11.3 Pre-push Hook with Modularization Check
 
@@ -659,7 +686,7 @@ Every standard must be machine-enforced to be effective.
 . "$(dirname -- "$0")/_/husky.sh"
 
 echo "Running quality checks..."
-pnpm lint && pnpm check-modularization && pnpm check-types && pnpm test:ci
+pnpm lint && pnpm check-security && pnpm check-modularization && pnpm check-types && pnpm test:ci
 ```
 
 ### 11.4 Modularization Validation Script
@@ -756,7 +783,23 @@ console.log(
 if (errors > 0) process.exit(1);
 ```
 
-### 11.5 Anti-Bypass (`--no-verify`) Protection
+### 11.5 Security Validation Script
+
+Add the security check to the consuming project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "check-security": "node scripts/check-security.mjs"
+  }
+}
+```
+
+Create `scripts/check-security.mjs` (or use the one provided by `@synergyerp/backend-standards` / its `check-backend-security` binary). The script scans the consuming project's `src/` directory and exits with code `1` when any of the violations listed in [Section 10.7](#107-automated-security-enforcement) are found.
+
+The script is pure ESM and only uses Node.js built-ins (`fs` and `path`), so it is compatible with any backend project without extra dependencies.
+
+### 11.6 Anti-Bypass (`--no-verify`) Protection
 
 The `git commit --no-verify` flag skips local hooks. Since CI runs the same checks independently, `--no-verify` only delays validation — it never bypasses it.
 
@@ -767,6 +810,9 @@ The `git commit --no-verify` flag skips local hooks. Since CI runs the same chec
 - name: Lint (catches --no-verify bypass)
   run: pnpm lint
 
+- name: Check Security (catches --no-verify bypass)
+  run: pnpm check-security
+
 - name: Check Modularization (catches --no-verify bypass)
   run: pnpm check-modularization
 
@@ -888,6 +934,7 @@ Standard `package.json` scripts:
     "test": "vitest",
     "lint": "eslint .",
     "check-modularization": "node scripts/check-modularization.mjs",
+    "check-security": "node scripts/check-security.mjs",
     "db:migrate": "prisma migrate deploy"
   }
 }

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@synergyerp/backend-standards",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "SynergyERP backend standards — ESLint, Prettier, commitlint, Husky, TypeScript configs, modularization enforcement, and PR templates.",
   "private": false,
   "type": "module",
   "main": "eslint.config.js",
+  "bin": {
+    "check-backend-security": "scripts/check-security.mjs"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -27,6 +30,7 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "check-security": "node scripts/check-security.mjs",
     "check-modularization": "node scripts/check-modularization.mjs; exit 0",
     "check-types": "tsc --noEmit; exit 0",
     "test:ci": "exit 0",

package/scripts/check-security.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+/**
+ * Backend Security Enforcement Hook
+ *
+ * Scans the consuming project's src/ directory for common backend security
+ * violations and fails if any are found.
+ *
+ * Enforces:
+ * 1. No raw SQL in template literals (outside .sql files / migration dirs).
+ * 2. No hardcoded secrets (api_key, password, secret, token string literals).
+ * 3. Response masking must be implemented (e.g., [REDACTED] or mask function).
+ * 4. Rate limiting must be used (express-rate-limit or similar).
+ * 5. Helmet must be used for security headers.
+ * 6. CORS must not use wildcard origins.
+ * 7. Input validation must be used (zod or class-validator).
+ * 8. Authorization / tokens must not be returned in response bodies.
+ *
+ * See: BACKEND_STANDARDS.md Sections 10 & 11
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { extname, join, relative } from 'path';
+
+const PROJECT_ROOT = process.cwd();
+const SRC_DIR = join(PROJECT_ROOT, 'src');
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+
+const errors = [];
+
+function logError(msg) {
+  console.error(`  ❌ ERROR: ${msg}`);
+  errors.push(msg);
+}
+
+function isSourceFile(file) {
+  return SOURCE_EXTENSIONS.has(extname(file));
+}
+
+function getAllSourceFiles(dir) {
+  const result = [];
+  if (!existsSync(dir)) return result;
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...getAllSourceFiles(path));
+    } else if (entry.isFile() && isSourceFile(path)) {
+      result.push(path);
+    }
+  }
+  return result;
+}
+
+function stripComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/.*$/gm, ' ');
+}
+
+function getLine(text, index) {
+  return text.substring(0, index).split('\n').length;
+}
+
+function rel(file) {
+  return relative(PROJECT_ROOT, file);
+}
+
+// ---------------------------------------------------------------------------
+// 1. Raw SQL in template literals
+// ---------------------------------------------------------------------------
+const SQL_KEYWORDS = ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'DROP', 'ALTER'];
+const SQL_TEMPLATE_ALLOWED_DIRS = ['migrations', 'migration', 'seeds', 'seed'];
+
+function isSQLAllowedPath(file) {
+  const lower = file.toLowerCase().replace(/\\/g, '/');
+  return lower.endsWith('.sql') || SQL_TEMPLATE_ALLOWED_DIRS.some((d) => lower.includes(`/${d}/`));
+}
+
+function checkRawSQL(file, content) {
+  if (isSQLAllowedPath(file)) return;
+
+  const templateRegex = /`([\s\S]*?)`/g;
+  let match;
+  while ((match = templateRegex.exec(content)) !== null) {
+    const literal = match[1];
+    const strippedLiteral = stripComments(literal);
+    for (const keyword of SQL_KEYWORDS) {
+      if (new RegExp(`\\b${keyword}\\b`, 'i').test(strippedLiteral)) {
+        logError(
+          `Raw SQL detected in ${rel(file)} (line ${getLine(content, match.index)}): ${keyword} inside template literal`
+        );
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Hardcoded secrets
+// ---------------------------------------------------------------------------
+const SECRET_NAMES = ['api_key', 'apikey', 'api-key', 'password', 'secret', 'token'];
+const secretRegex = new RegExp(
+  `\\b(?:${SECRET_NAMES.join('|')})(?:[_-]?(?:key|hash|salt|token|secret))?\\s*[:=]\\s*(["'])(?!\\$\\{)(?:(?!\\1).)+\\1`,
+  'gi'
+);
+
+function isEnvVarLine(line) {
+  return /process\.env\./i.test(line) || /import\.meta\.env\./i.test(line);
+}
+
+function checkHardcodedSecrets(file, content) {
+  const lines = content.split('\n');
+  let match;
+  while ((match = secretRegex.exec(content)) !== null) {
+    const lineNumber = getLine(content, match.index);
+    const line = lines[lineNumber - 1] || '';
+    if (isEnvVarLine(line)) continue;
+    if (line.trim().startsWith('//')) continue;
+
+    logError(`Hardcoded secret detected in ${rel(file)} (line ${lineNumber}): ${match[0].trim()}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 3. Response masking
+// ---------------------------------------------------------------------------
+function hasResponseMasking(file, content) {
+  return (
+    /\[REDACTED\]/i.test(content) ||
+    /\bmask\s*\(/i.test(content) ||
+    /\bmaskSensitive/i.test(content)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 4. Rate limiting
+// ---------------------------------------------------------------------------
+function hasRateLimiting(file, content) {
+  return (
+    /express-rate-limit/i.test(content) ||
+    /rateLimit\s*\(/i.test(content) ||
+    /rate[-_]?limit/i.test(content)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 5. Helmet
+// ---------------------------------------------------------------------------
+function hasHelmet(file, content) {
+  return /\bhelmet\s*\(/i.test(content) || /helmet\(/i.test(content);
+}
+
+// ---------------------------------------------------------------------------
+// 6. CORS wildcard
+// ---------------------------------------------------------------------------
+function checkCORSWildcard(file, content) {
+  const originWildcardRegex = /origin\s*:\s*['"]\*['"]/i;
+  if (originWildcardRegex.test(content)) {
+    logError(`CORS wildcard origin detected in ${rel(file)}`);
+  }
+
+  const corsRegex = /cors\s*\(\s*\)/i;
+  if (corsRegex.test(content)) {
+    logError(`CORS called without explicit whitelist in ${rel(file)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 7. Input validation
+// ---------------------------------------------------------------------------
+function hasInputValidation(file, content) {
+  return /zod/i.test(content) || /class-validator/i.test(content) || /joi/i.test(content);
+}
+
+// ---------------------------------------------------------------------------
+// 8. Exposed Authorization / tokens in response bodies
+// ---------------------------------------------------------------------------
+function checkExposedAuth(file, content) {
+  const responseRegex = /res\.(?:json|send|status\([^)]*\)\.(?:json|send))\s*\(/i;
+  const authFieldRegex =
+    /['"]?(?:token|authorization|accessToken|refreshToken|api_key|apikey|secret)['"]?\s*:/i;
+
+  if (responseRegex.test(content) && authFieldRegex.test(content)) {
+    logError(`Sensitive auth/token field exposed in response body in ${rel(file)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+console.log('\n🔐 Checking backend security standards...\n');
+
+if (!existsSync(SRC_DIR)) {
+  console.log('  No src/ directory found. Skipping.\n');
+  process.exit(0);
+}
+
+const files = getAllSourceFiles(SRC_DIR);
+if (files.length === 0) {
+  console.log('  No source files found in src/. Skipping.\n');
+  process.exit(0);
+}
+
+let maskingFound = false;
+let rateLimitingFound = false;
+let helmetFound = false;
+let inputValidationFound = false;
+
+for (const file of files) {
+  const content = readFileSync(file, 'utf-8');
+
+  checkRawSQL(file, content);
+  checkHardcodedSecrets(file, content);
+  checkCORSWildcard(file, content);
+  checkExposedAuth(file, content);
+
+  if (hasResponseMasking(file, content)) maskingFound = true;
+  if (hasRateLimiting(file, content)) rateLimitingFound = true;
+  if (hasHelmet(file, content)) helmetFound = true;
+  if (hasInputValidation(file, content)) inputValidationFound = true;
+}
+
+if (!maskingFound) {
+  logError('Missing response masking (no [REDACTED] or mask() function found in src/)');
+}
+
+if (!rateLimitingFound) {
+  logError('Missing rate limiting (no express-rate-limit or rateLimit() usage found in src/)');
+}
+
+if (!helmetFound) {
+  logError('Missing helmet security headers (no helmet() usage found in src/)');
+}
+
+if (!inputValidationFound) {
+  logError('Missing input validation (no zod/class-validator/joi usage found in src/)');
+}
+
+console.log(
+  `\n${errors.length === 0 ? '✅' : '❌'} Backend security check complete. Errors: ${errors.length}\n`
+);
+
+if (errors.length > 0) {
+  process.exit(1);
+}
+process.exit(0);