cerber-core 1.1.6 → 1.1.7

package/CHANGELOG.md

@@ -5,6 +5,117 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.7] - 2026-01-04
+
+### Added
+
+#### 🩺 `npx cerber doctor` - Setup Validation Command
+- New diagnostic command validates Cerber installation
+- Checks: `CERBER.md`, schema file (strict mode), hooks, workflow
+- Returns stable exit codes: 0=OK, 2=missing contract, 3=missing schema, 4=missing hooks/workflow
+- Shows override state: DISABLED/ACTIVE/EXPIRED/INVALID
+- Prints actionable "Next Steps" for each failure scenario
+- MVP implementation (ASCII-only output for stability)
+
+#### 🛡️ `CERBER_GUARDRAILS` - Protected Assets Declaration
+- Added to `CERBER.md` template
+- Documents protected files: contract, schema, workflow, guardian, hooks, CODEOWNERS
+- Change policy: never delete/disable, never rename job IDs
+- Allowed changes: schema rules (must match contract), CI config with PR justification
+- Emergency override placeholder for TTL mechanism
+
+#### 🔐 Self-Protection Mechanisms
+
+**cerber-integrity Workflow Job:**
+- New first job (runs before `cerber-ci`)
+- Validates protected files exist
+- In strict mode: checks schema file presence
+- Verifies `cerber-ci` job ID intact (prevents sabotage)
+- **Cannot be skipped or disabled** (fail-safe)
+
+**CODEOWNERS Protection (Team Mode):**
+- Now includes all Cerber files: contract, schema, workflow, guardian, hooks
+- Self-protection: `/.github/CODEOWNERS` requires owner approval
+- Prevents unauthorized changes to enforcement infrastructure
+
+#### 🚨 Emergency Override (TTL-based, Controlled)
+
+**`CERBER_OVERRIDE` Contract Section:**
+- Time-to-live based safety fuse (NOT a power switch)
+- Required fields when enabled: `reason`, `expires` (ISO 8601), `approvedBy`
+- If expired → treated as disabled
+- If invalid (missing fields) → treated as disabled
+
+**What Override DOES:**
+- ✅ Pre-commit: Allows commit WITH WARNING (prints full metadata)
+- ✅ Post-deploy: May skip health gate (if flaky/blocking hotfix)
+
+**What Override NEVER DOES (Hard Limits):**
+- ❌ NEVER disables `cerber-integrity` job
+- ❌ NEVER disables entire CI pipeline
+- ❌ NEVER disables `cerber-ci` validation
+- ❌ NEVER bypasses CODEOWNERS (team mode)
+
+**Implementation:**
+- Guardian checks override at startup
+- Doctor shows override state
+- Override metadata printed for audit trail
+- Applied to all modes: solo, dev, team
+
+#### 🔒 Guided Schema Templates (Security Baseline)
+- Added commented security patterns to `BACKEND_SCHEMA.mjs` template
+- Categories: hardcoded secrets, dev artifacts, critical TODOs
+- Examples: `password=`, `API_KEY=`, `JWT_SECRET=`, `console.log`, `debugger`
+- Clear instruction: "Uncomment patterns that match rules in your CERBER.md"
+- Enforces "never invent rules" principle (translation only)
+
+#### 📦 Supply-Chain Security Policy
+- Updated `SECURITY.md` with comprehensive supply-chain guidance
+- npm 2FA required for all maintainers
+- CI-only publishing strongly recommended
+- No risky lifecycle scripts (`postinstall`, `preinstall`)
+- Dependencies updated only via reviewed PRs
+- Installation safety guarantees documented
+- Package verification steps provided
+- Compromise response procedures added
+
+#### 🛡️ Generator Path Safety
+- Resolves repository root via `git rev-parse --show-toplevel`
+- Writes ONLY inside repository root (fail-closed if root unknown)
+- Blocks `..` path traversal attempts
+- Whitelists allowed outputs (contract, schema, workflow, guardian, hooks, CODEOWNERS)
+- Validates every file path before write operation
+- Path traversal protection prevents security issues with malicious contracts
+
+### Changed
+
+#### 📝 Hardened "For AI Agents" Section (README)
+
+**New MUST Rules:**
+1. **Schema Generation = Translation Only**
+   - Agent can ONLY translate explicit rules from `CERBER.md`
+   - If rule not in `CERBER.md` → ask user / fail / leave empty
+   - Never invent, guess, or auto-generate architecture rules
+
+2. **NO-HEREDOC for TS/JS Files**
+   - Never create TypeScript/JavaScript files using bash `cat <<EOF`
+   - Reason: Causes `${}` template literal corruption and UTF-8 encoding issues
+   - Use editor tools, `fs.writeFile`, or proper file generation utilities
+
+### Fixed
+- Added final newline to `CODEOWNERS.tpl` (prevented last line truncation)
+
+### Security
+- **Supply-chain hardening**: No postinstall scripts, 2FA required, CI-only publish
+- **Path safety**: Generator validates all file writes (repo-root + whitelist)
+- **Self-protection**: cerber-integrity job prevents sabotage/deletion
+- **Emergency override**: Controlled bypass with TTL and audit trail (never disables integrity)
+
+### Breaking Changes
+None. All changes are backward compatible with existing Cerber installations.
+
+---
+
 ## [1.1.4] - 2026-01-04
 
 ### Fixed

package/README.md

@@ -52,6 +52,18 @@ npx cerber init
 
 **Working with Cerber:** Read `CERBER.md` first. It tells you what's allowed and what's protected.
 
+### MUST (Non-Negotiable Rules for AI Agents)
+
+**Rule 1: Schema Generation = Translation Only**
+- Agent can **only translate** explicit rules from `CERBER.md` into `BACKEND_SCHEMA.*` format
+- If a rule is **not in CERBER.md** → ask user / fail / leave empty
+- **Never invent**, guess, or auto-generate architecture rules
+
+**Rule 2: NO-HEREDOC for TS/JS Files**
+- **Never** create TypeScript/JavaScript files using bash `cat <<EOF` or heredoc syntax
+- Reason: Causes `${}` template literal corruption and UTF-8 encoding issues
+- Use editor tools, `fs.writeFile`, or proper file generation utilities instead
+
 ---
 
 ## 📊 Real Production Metrics
@@ -511,6 +523,9 @@ cat .cerber/FOCUS_CONTEXT.md
 All features available through unified CLI:
 
 ```bash
+# Doctor - Setup validation (new in v1.1.7)
+npx cerber doctor              # Validate CERBER.md, schema, hooks, CI
+
 # Guardian - Pre-commit validation
 cerber guardian --schema ./SCHEMA.ts
 
@@ -537,6 +552,54 @@ cerber-focus
 
 ---
 
+## 🩺 npx cerber doctor (New in v1.1.7)
+
+Validate your Cerber setup before commits or deploys:
+
+```bash
+npx cerber doctor
+```
+
+**Exit codes:**
+- `0` ✅ All checks pass
+- `2` ❌ Missing CERBER.md
+- `3` ❌ Missing schema (strict mode only)
+- `4` ❌ Missing pre-commit hook or CI workflow
+
+**What it checks:**
+- CERBER.md present + valid YAML
+- Schema file exists (if `schema.mode: strict`)
+- `.husky/pre-commit` hook installed (if `guardian.enabled: true`)
+- GitHub Actions workflow present (if `ci.provider: github`)
+- Emergency override state (DISABLED | ACTIVE | EXPIRED | INVALID)
+
+**Example output:**
+
+```
+🩺 Cerber Doctor - Setup Validation
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ CERBER.md: Found and valid
+✓ Schema: BACKEND_SCHEMA.mjs exists
+✓ Pre-commit hook: Installed (.husky/pre-commit)
+✓ CI workflow: Found (.github/workflows/cerber.yml)
+  Override: DISABLED
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ All checks passed (exit 0)
+```
+
+**Use in CI:**
+
+```yaml
+- name: Validate Cerber setup
+  run: npx cerber doctor
+```
+
+If doctor fails → build fails → prevents incomplete Cerber deployments.
+
+---
+
 ## ⚠️ Important: Schema Files Are NOT Source of Truth
 
 Before diving into examples below, understand this:
@@ -1589,12 +1652,103 @@ Include:
 
 **Response time:** 24-48 hours acknowledgment, 7-14 days for fix.
 
+---
+
+## 🚨 Emergency Override (New in v1.1.7)
+
+For **critical production hotfixes only** (P0 incidents), Cerber provides a **controlled safety fuse** with strict time limits.
+
+### What Override DOES ✅
+
+- Allows pre-commit to pass **WITH WARNING** (audit trail logged)
+- Can skip `postDeploy` gate if configured
+- Requires: reason, expiry timestamp (TTL), approver name
+- Automatically expires (guardian validates TTL)
+
+### What Override NEVER DOES ❌
+
+Override is a **safety fuse**, NOT a power switch. It **NEVER** disables:
+
+- ❌ `cerber-integrity` job (self-protection always runs)
+- ❌ Entire CI pipeline (build, test, lint must pass)
+- ❌ `cerber-ci` workflow job (contract validation always runs)
+- ❌ CODEOWNERS enforcement (team mode protection)
+
+### Example: P0 Hotfix
+
+```yaml
+## CERBER_OVERRIDE
+enabled: true
+reason: "P0 - Payment API down, emergency rollback required"
+expires: "2026-01-04T18:00:00Z"  # 6-hour TTL
+approvedBy: "CTO Stefan"
+```
+
+**Guardian behavior:**
+
+```bash
+git commit -m "fix: rollback payment API to v1.2.3"
+
+⚠️  CERBER EMERGENCY OVERRIDE ACTIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Reason:     P0 - Payment API down, emergency rollback required
+Expires:    2026-01-04T18:00:00Z (5h 23m remaining)
+Approved:   CTO Stefan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Guardian checks: BYPASSED WITH WARNING
+Self-protection: STILL ACTIVE (cerber-integrity runs)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[main 3a7f2e9] fix: rollback payment API to v1.2.3
+```
+
+**CI behavior:**
+
+- ✅ `cerber-integrity` job **runs** (validates CERBER.md, override metadata)
+- ✅ Build, test, lint jobs **run**
+- ✅ `cerber-ci` job **runs** (contract validation)
+- ⚠️ Override warning shown in CI logs (audit trail)
+
+**After expiry:**
+
+```bash
+git commit -m "feat: add new feature"
+
+❌ CERBER EMERGENCY OVERRIDE EXPIRED
+Override expired at: 2026-01-04T18:00:00Z
+Proceeding with normal validation...
+
+❌ Schema validation failed: Missing type annotation for handlePayment()
+```
+
+### Verification
+
+```bash
+npx cerber doctor
+# Shows: Override: ACTIVE (expires 2026-01-04T18:00:00Z)
+# Or: Override: EXPIRED (expired 2h ago)
+# Or: Override: DISABLED
+```
+
+### Rules
+
+1. **All fields required:** enabled, reason, expires, approvedBy (missing = invalid = disabled)
+2. **TTL enforced:** Guardian checks expiry timestamp (expired = proceeds with normal validation)
+3. **Audit trail:** All commits with active override logged with full metadata
+4. **No carte blanche:** Hard limits enforced (integrity, CI, CODEOWNERS never bypassed)
+
+**Use sparingly.** Override is for emergencies, not convenience.
+
+---
+
 ### Security Features
 
 ✅ **No External Calls:** Guardian and Cerber run locally, no data sent externally  
 ✅ **Open Source:** Full transparency - audit the code yourself  
 ✅ **No Telemetry:** No tracking, no analytics, no data collection  
 ✅ **MIT Licensed:** Safe for commercial use  
+✅ **Supply-Chain Hardened:** 2FA, CI-only publishing, no risky lifecycle scripts (v1.1.7)  
+✅ **Path Safety:** Generator writes only to repo root, whitelist-validated paths (v1.1.7)  
 
 ### Best Practices
 
@@ -1603,8 +1757,10 @@ Include:
 - Update regularly: `npm update cerber-core`
 - Enable Dependabot for automated security updates
 - Run `npm audit` regularly
+- Review CERBER.md changes in PRs (protected by CODEOWNERS in team mode)
+- Use emergency override sparingly (P0 incidents only)
 
-**Full security policy:** [SECURITY.md](SECURITY.md)
+**Full security policy:** [SECURITY.md](SECURITY.md) (includes supply-chain security, vulnerability reporting, supported versions)
 
 ---
 

package/bin/cerber

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * Cerber Core - Unified CLI
@@ -118,4 +118,17 @@ program
     execSync('node solo/scripts/cerber-dashboard.js', { stdio: 'inherit' });
   });
 
+
+program
+  .command('doctor')
+  .description('Validate Cerber setup (checks for missing files)')
+  .action(async () => {
+    const { runDoctor, printDoctorReport } = await import('../dist/cli/doctor.js');
+    const result = await runDoctor(process.cwd());
+    printDoctorReport(result);
+    process.exit(result.exitCode);
+  });
+
+program.parse();
+
 program.parse();

package/dev/templates/BACKEND_SCHEMA.ts.tpl

@@ -1,50 +1,87 @@
-/**
- * ⚠️  CERBER TEMPLATE (NOT SOURCE OF TRUTH)
- * 
- * This file is a starting point. Edit it to match YOUR architecture.
- * The source of truth is CERBER.md.
- * 
- * Generated by: npx cerber init
- * Project: {{PROJECT_NAME}}
- * 
- * See: https://github.com/Agaslez/cerber-core#guardian-configuration
- */
-
-export const BACKEND_SCHEMA = {
-  version: "1.0.0",
-  
-  // Your architecture rules (customize)
-  rules: [],
-  
-  // Patterns that should never appear in your code
-  forbiddenPatterns: [
-    // Uncomment and customize based on your tech stack:
-    // {
-    //   pattern: "password\\s*=\\s*['\"][^'\"]+['\"]",
-    //   flags: "i",
-    //   name: "Hardcoded passwords",
-    //   severity: "error"
-    // },
-    // {
-    //   pattern: "api[_-]?key\\s*=\\s*['\"][^'\"]+['\"]",
-    //   flags: "i",
-    //   name: "Hardcoded API keys",
-    //   severity: "error"
-    // }
-  ]
-};
-
-export default BACKEND_SCHEMA;
-
-/**
- * 💡 Next Steps:
- * 
- * 1. Define your project structure in CERBER.md (single source of truth)
- * 2. Add forbiddenPatterns for your tech stack
- * 3. Add requiredImports rules for your architecture layers
- * 4. Test with: npx cerber-guardian
- * 
- * Full examples:
- * - node_modules/cerber-core/examples/backend-schema.ts
- * - node_modules/cerber-core/examples/frontend-schema.ts
- */
+/**
+ * ⚠️  CERBER TEMPLATE (NOT SOURCE OF TRUTH)
+ * 
+ * This file is a starting point. Edit it to match YOUR architecture.
+ * The source of truth is CERBER.md.
+ * 
+ * Generated by: npx cerber init
+ * Project: {{PROJECT_NAME}}
+ * 
+ * See: https://github.com/Agaslez/cerber-core#guardian-configuration
+ */
+
+export const BACKEND_SCHEMA = {
+  version: "1.0.0",
+  
+  // Your architecture rules (customize)
+  rules: [],
+  
+  // Patterns that should never appear in your code
+  forbiddenPatterns: [
+    // ──────────────────────────────────────────────────────────────────────
+    // 🔐 SECURITY BASELINE (Uncomment and adapt to your CERBER.md contract)
+    // ──────────────────────────────────────────────────────────────────────
+    
+    // Hardcoded secrets (common examples - adapt to your stack):
+    // {
+    //   pattern: "password\\s*=\\s*['\"][^'\"]+['\"]"  ,
+    //   flags: "i",
+    //   name: "Hardcoded passwords (e.g., password='admin123')",
+    //   severity: "error"
+    // },
+    // {
+    //   pattern: "api[_-]?key\\s*=\\s*['\"][^'\"]+['\"]"  ,
+    //   flags: "i",
+    //   name: "Hardcoded API keys (e.g., API_KEY='xyz')",
+    //   severity: "error"
+    // },
+    // {
+    //   pattern: "JWT_SECRET\\s*=\\s*['\"][^'\"]+['\"]"  ,
+    //   flags: "i",
+    //   name: "Hardcoded JWT secrets",
+    //   severity: "error"
+    // },
+    
+    // Development artifacts (should not reach production):
+    // {
+    //   pattern: "console\\.log\\(",
+    //   flags: "g",
+    //   name: "console.log (use proper logging)",
+    //   severity: "warning"
+    // },
+    // {
+    //   pattern: "debugger;",
+    //   flags: "g",
+    //   name: "debugger statement",
+    //   severity: "warning"
+    // },
+    
+    // TODOs that should be resolved before commit:
+    // {
+    //   pattern: "TODO_REMOVE|FIXME_REMOVE",
+    //   flags: "i",
+    //   name: "Unresolved critical TODOs",
+    //   severity: "error"
+    // },
+    
+    // ──────────────────────────────────────────────────────────────────────
+    // ⚠️  IMPORTANT: Uncomment patterns that match rules in your CERBER.md
+    // Never invent rules. Only translate what's documented in your contract.
+    // ──────────────────────────────────────────────────────────────────────
+  ]
+};
+
+export default BACKEND_SCHEMA;
+
+/**
+ * 💡 Next Steps:
+ * 
+ * 1. Define your project structure in CERBER.md (single source of truth)
+ * 2. Add forbiddenPatterns for your tech stack
+ * 3. Add requiredImports rules for your architecture layers
+ * 4. Test with: npx cerber-guardian
+ * 
+ * Full examples:
+ * - node_modules/cerber-core/examples/backend-schema.ts
+ * - node_modules/cerber-core/examples/frontend-schema.ts
+ */