@smartergpt/lexrunner 1.0.0

package/docs/SECURITY_IMPLEMENTATION.md

@@ -0,0 +1,535 @@
+# Enterprise Security & Compliance Implementation Summary
+
+## Overview
+
+This implementation adds comprehensive enterprise-grade security and compliance features to lexrunner, enabling production deployment in regulated environments.
+
+## Implemented Features
+
+### ✅ 1. Authentication & Authorization Framework
+
+**Files:**
+
+- `src/security/authentication.ts` - Authentication providers and token management
+- `src/security/authorization.ts` - RBAC and permission system
+
+**Features:**
+
+- GitHub token authentication with validation
+- Extensible authentication provider interface
+- Role-based access control (RBAC) with predefined roles
+- Permission-based autopilot level restrictions
+- Fine-grained operation permissions
+
+**Roles & Permissions:**
+
+- `viewer` → Level 0 (READ only)
+- `developer` → Level 2 (READ, ARTIFACTS, ANNOTATE)
+- `integrator` → Level 3 (+ CREATE_PR)
+- `releaseManager` → Level 4 (+ MERGE)
+- `admin` → All permissions
+
+### ✅ 2. Enhanced Audit Logging
+
+**Files:**
+
+- `src/security/compliance.ts` - Enterprise audit trail with digital signatures
+
+**Features:**
+
+- Cryptographic hashing of audit entries (SHA-256)
+- HMAC digital signatures for tamper detection
+- Secure audit entry storage with auth context
+- Actor tracking and correlation IDs
+- Merge operation audit trail with full details
+
+**Compliance Exports:**
+
+- **SOX** - Sarbanes-Oxley compliance format
+- **SOC2** - Service Organization Control 2 format
+- **CSV** - Spreadsheet analysis format
+- **JSON/JSONL** - Machine-readable formats
+
+### ✅ 3. Digital Signatures
+
+**Implementation:**
+
+- HMAC-SHA256 signatures for audit entries
+- Hash-based tamper detection
+- Signature verification with key validation
+- Report signing for compliance exports
+
+**Usage:**
+
+```typescript
+const auditService = new EnterpriseAuditService(process.env.AUDIT_SIGNING_KEY);
+const entry = auditService.logSecure("operation", "decision", metadata, authContext);
+const isValid = auditService.verifyEntry(entry); // Verify integrity
+```
+
+### ✅ 4. Secrets Management
+
+**Files:**
+
+- `src/security/secrets.ts` - Secure credential handling
+- `scripts/rotate-secrets-example.ts` - Example rotation script
+
+**Features:**
+
+- Environment variable integration with prefix support
+- Secret provider abstraction for extensibility
+- Automatic GitHub token discovery (GITHUB_TOKEN, GH_TOKEN, GITHUB_PAT)
+- Secret rotation detection based on age
+- Secret redaction for logs and output
+- Cache management with automatic expiry
+
+**Security:**
+
+- Secrets never logged in plaintext
+- Automatic redaction in error messages
+- Rotation warnings for aged credentials
+
+**Rotation Guide:**
+
+- See [docs/security/rotation-guide.md](security/rotation-guide.md) for:
+  - Recommended rotation cadences by secret type
+  - Compliance framework requirements (SOX, PCI-DSS, SOC 2, HIPAA)
+  - Step-by-step rotation workflows
+  - Automation patterns and CI/CD integration
+  - Emergency rotation procedures
+
+### ✅ 5. Security Scanning Integration
+
+**Files:**
+
+- `src/security/scanning.ts` - Vulnerability detection
+- `src/security/sarif.ts` - SARIF format parser
+
+**Features:**
+
+- NPM audit integration for dependency scanning
+- SARIF (Static Analysis Results Interchange Format) 2.1.0 support
+- CVE and CVSS tracking
+- Severity-based policy enforcement (CRITICAL, HIGH, MEDIUM, LOW)
+- Configurable vulnerability thresholds
+- Detailed vulnerability reporting with fix recommendations
+
+**Vuln Gate:**
+The `vuln` gate provides artifact-based vulnerability scanning:
+
+- Automatically detects and parses SARIF files (`scan-results.sarif`)
+- Falls back to npm audit JSON (`npm-audit.json`) when SARIF not available
+- Enforces security policy thresholds configured in `plan.policy.security`
+- Provides deterministic, structured output with severity counts
+
+**Policy Controls:**
+
+- Block critical vulnerabilities (`blockCritical: true`)
+- Block high vulnerabilities (`blockHigh: true`)
+- Maximum allowed medium vulnerabilities (`maxMedium: 5`)
+- Maximum allowed low vulnerabilities (`maxLow: 10`)
+- Custom scanner integration support
+
+**Example Configuration:**
+
+```json
+{
+  "policy": {
+    "requiredGates": ["vuln"],
+    "security": {
+      "blockCritical": true,
+      "blockHigh": true,
+      "maxMedium": 5,
+      "maxLow": 10
+    }
+  },
+  "items": [
+    {
+      "name": "feature-branch",
+      "gates": [
+        {
+          "name": "vuln",
+          "run": "trivy fs --format sarif --output scan-results.sarif ."
+        }
+      ]
+    }
+  ]
+}
+```
+
+### ✅ 6. Compliance Policy Enforcement
+
+**Files:**
+
+- `src/security/policy.ts` - Policy rules and enforcement
+
+**Features:**
+
+- **Approval Requirements:**
+  - Minimum approval count
+  - Required reviewer roles
+  - Code owner approval requirements
+  - Stale approval dismissal
+
+- **Branch Protection:**
+  - Pattern-based branch rules
+  - Status check requirements
+  - Push restrictions by role
+
+- **Merge Restrictions:**
+  - Allowed merge strategies (merge/squash/rebase)
+  - Linear history enforcement
+  - Signed commit requirements
+  - Force push blocking
+
+### ✅ 7. Comprehensive Testing
+
+**Test Coverage:**
+
+- `tests/security-authentication.spec.ts` (5 tests)
+- `tests/security-authorization.spec.ts` (16 tests)
+- `tests/security-compliance.spec.ts` (15 tests)
+- `tests/security-secrets.spec.ts` (19 tests)
+- `tests/security-policy.spec.ts` (18 tests)
+
+**Total: 73 security tests, all passing ✓**
+
+### ✅ 8. Documentation & Examples
+
+**Documentation:**
+
+- `src/security/README.md` - Comprehensive module documentation
+- `examples/security-integration.ts` - Full integration example
+
+**Guides:**
+
+- Authentication setup
+- Authorization configuration
+- Audit logging best practices
+- Secrets management
+- Security scanning integration
+- Policy enforcement configuration
+
+### ✅ 9. Security CLI Exit Semantics (B5 Placeholder)
+
+| Exit Code | Meaning                                          | Status Mapping | Retry Guidance                           |
+| --------- | ------------------------------------------------ | -------------- | ---------------------------------------- |
+| 0         | Success / No findings                            | `ok`           | Not required                             |
+| 1         | Findings detected (actionable issues, non-fatal) | `findings`     | Address & re-run                         |
+| 2         | Internal error (unexpected failure)              | `error`        | Investigate infrastructure / stack trace |
+
+Stability: Codes 0–2 are reserved and will not change without a documented major version bump.
+
+### ✅ 10. Retention Trimming Contract (B4/B5)
+
+`EnterpriseAuditService.trimRetention(retentionDays?, framework?)` (non-destructive preview) returns:
+
+```jsonc
+{
+  "total": 150, // total audit entries
+  "trimmed": 42, // entries older than applied retention
+  "kept": 108, // total - trimmed
+  "retentionDaysApplied": 365, // resolved from args or framework default
+  "framework": "ISO 27001", // canonical display name if framework recognized
+  "supportedFrameworks": ["GDPR", "HIPAA", "ISO 27001", "PCI DSS", "SOC2", "SOX"],
+}
+```
+
+Aliases: `iso27001`, `soc-2`, `sarbanesoxley`, `pci` map to their canonical forms via normalization.
+
+Determinism: `supportedFrameworks` is sorted and stable across runs.
+
+## Architecture
+
+### Integration with Existing Systems
+
+1. **Autopilot Integration:**
+   - Authorization checks before autopilot execution
+   - Permission-based level restrictions
+   - Audit logging for all autopilot operations
+
+2. **Safety Framework Integration:**
+   - Complements existing safety controls
+   - Adds cryptographic audit trail
+   - Enhanced rollback with audit
+
+3. **Monitoring Integration:**
+   - Extends base audit trail with signatures
+   - Compliance reporting on top of monitoring
+   - Unified correlation ID tracking
+
+### Security Flow
+
+```
+┌─────────────────┐
+│ Authentication  │ → Validate token, extract roles
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Authorization   │ → Check permissions for operation
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Secrets Mgmt    │ → Load required credentials
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Security Scan   │ → Check for vulnerabilities
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Policy Check    │ → Enforce compliance rules
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Execute         │ → Run authorized operation
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ Audit Log       │ → Sign and store audit trail
+└─────────────────┘
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Authentication
+export GITHUB_TOKEN="ghp_..."
+
+# Audit Signing
+export AUDIT_SIGNING_KEY="your-hmac-key"
+
+# Secrets (with LEX_PR_ prefix)
+export LEX_PR_API_KEY="..."
+export LEX_PR_DATABASE_URL="..."
+```
+
+### Policy Configuration
+
+```typescript
+import { CompliancePolicyService } from "./security";
+
+const policy = new CompliancePolicyService({
+  reviewPolicy: {
+    requireReview: true,
+    approvalRequirement: {
+      minApprovals: 2,
+      requireCodeOwners: true,
+      dismissStaleApprovals: true,
+    },
+    allowSelfApproval: false,
+    requireConversationResolution: true,
+  },
+  branchProtections: [
+    {
+      pattern: "main",
+      requireStatusChecks: true,
+      requiredChecks: ["ci/test", "ci/lint", "security/scan"],
+      restrictPushers: true,
+      allowedPushers: ["admin", "releaseManager"],
+    },
+  ],
+  mergeRestrictions: {
+    allowedStrategies: ["squash"],
+    requireLinearHistory: true,
+    requireSignedCommits: true,
+    blockForcePush: true,
+  },
+  requireSecurityScan: true,
+  maxVulnerabilitySeverity: "high",
+});
+```
+
+## Usage Examples
+
+### Basic Secure Execution
+
+```typescript
+import { AuthenticationManager, AuthorizationService, EnterpriseAuditService } from "./security";
+
+// Authenticate
+const authManager = new AuthenticationManager();
+const authContext = await authManager.initialize();
+
+// Authorize
+const authService = new AuthorizationService();
+authService.enforceAutopilotLevel(authContext, 4);
+
+// Audit
+const auditService = new EnterpriseAuditService(signingKey);
+auditService.logMergeOperation(
+  {
+    prNumbers: [101, 102],
+    targetBranch: "main",
+    mergeStrategy: "squash",
+    gateResults: { lint: "passed", test: "passed" },
+    decision: "approved",
+  },
+  authContext
+);
+```
+
+### Compliance Reporting
+
+```typescript
+import { EnterpriseAuditService, ComplianceFormat } from "./security";
+
+const auditService = new EnterpriseAuditService(signingKey);
+
+// Generate SOC2 report
+const report = auditService.generateComplianceReport(
+  ComplianceFormat.SOC2,
+  "2024-01-01T00:00:00Z",
+  "2024-12-31T23:59:59Z"
+);
+
+// Export for audit
+auditService.exportReport(report, "./compliance/soc2-2024.json");
+```
+
+## Testing & Validation
+
+### Run Security Tests
+
+```bash
+# All security tests
+npm test -- tests/security
+
+# Specific test suites
+npm test -- tests/security-authentication.spec.ts
+npm test -- tests/security-authorization.spec.ts
+npm test -- tests/security-compliance.spec.ts
+npm test -- tests/security-secrets.spec.ts
+npm test -- tests/security-policy.spec.ts
+```
+
+### Build & Type Check
+
+```bash
+npm run typecheck  # Type safety
+npm run build      # Production build
+npm test          # Full test suite (664 tests)
+```
+
+## Production Deployment
+
+### Prerequisites
+
+1. **GitHub Token** with appropriate scopes
+2. **Audit Signing Key** for cryptographic signatures
+3. **Role Mapping** for organization users
+4. **Policy Configuration** for compliance requirements
+5. **Security Scanners** configured (npm audit, etc.)
+
+### Deployment Steps
+
+1. Set environment variables:
+
+   ```bash
+   export GITHUB_TOKEN="..."
+   export AUDIT_SIGNING_KEY="..."
+   ```
+
+2. Configure policies:
+
+   ```typescript
+   const policy = new CompliancePolicyService({
+     /* config */
+   });
+   ```
+
+3. Initialize security:
+
+   ```typescript
+   const authManager = new AuthenticationManager();
+   const authContext = await authManager.initialize();
+   ```
+
+4. Run with audit:
+   ```bash
+   lex-pr autopilot --level 4 --audit-signed
+   ```
+
+### Security CLI Commands
+
+The `lex-pr security` command provides security operations:
+
+```bash
+# Check if secrets need rotation
+lex-pr security check-rotation GITHUB_TOKEN API_KEY --max-age 90
+
+# Scan plan files for accidentally exposed secrets
+lex-pr security scan-plan plan.json
+
+# Validate required secrets are present
+lex-pr security validate-secrets GITHUB_TOKEN DATABASE_URL
+```
+
+### Monitoring
+
+- Review audit logs regularly
+- Generate compliance reports monthly
+- Check for secret rotation needs with `lex-pr security check-rotation`
+- Use rotation example script: `tsx scripts/rotate-secrets-example.ts`
+- See [rotation guide](security/rotation-guide.md) for automation patterns
+- Monitor security scan results
+- Track permission usage
+- Apply retention policies based on compliance framework (SOX, GDPR, etc.)
+
+## Security Best Practices
+
+1. ✅ **Use environment variables** for all sensitive data
+2. ✅ **Enable audit signing** in production
+3. ✅ **Configure strict branch protection** for main/release
+4. ✅ **Require code owner approval** for critical changes
+5. ✅ **Run security scans** before every merge
+6. ✅ **Rotate secrets regularly** (check with `checkRotationNeeded`)
+7. ✅ **Use minimum permissions** (principle of least privilege)
+8. ✅ **Review audit logs** for anomalies
+9. ✅ **Export compliance reports** for auditors
+10. ✅ **Validate required secrets** before execution
+
+## Compliance Certifications
+
+This implementation provides the foundation for:
+
+- **SOX Compliance** - Audit trail and change controls
+- **SOC2 Type II** - Access controls and monitoring
+- **GDPR** - Data handling and audit requirements
+- **HIPAA** - Access controls and audit logging
+- **ISO 27001** - Information security management
+
+## Future Enhancements
+
+Potential extensions:
+
+- OAuth/SAML integration for SSO
+- HashiCorp Vault integration for secrets
+- Custom security scanner plugins
+- Automated policy generation
+- Real-time security dashboards
+- Compliance automation workflows
+
+## Support & Documentation
+
+- **Module Docs:** `src/security/README.md`
+- **Examples:** `examples/security-integration.ts`
+- **Tests:** `tests/security-*.spec.ts`
+- **API Reference:** Individual module files
+
+## Related Issues
+
+- Issue #77 - Rollout Infrastructure & Production Readiness
+- Issue #106 - Related security requirements
+
+---
+
+**Status:** ✅ Complete - All acceptance criteria met
+
+**Test Coverage:** 73 tests, all passing
+
+**Documentation:** Complete with examples
+
+**Production Ready:** Yes

package/docs/TERMS.md

@@ -0,0 +1,34 @@
+# lexrunner — Canonical Terms
+
+## Project & Components
+
+- **lexrunner (project/repo)**: The repository you're reading.
+- **Runner CLI (core runner)**: TypeScript command-line app under `src/**`. Shorthand: "the runner".
+- **MCP server (adapter)**: Optional read-only adapter at `src/mcp/server.ts`. Shorthand: "lex-pr MCP".
+- **Workspace profile**: Portable example profile under `.smartergpt/**`. Not the app; it's inputs the runner consumes.
+- **Merge pyramid**: The plan → gates → weave/merge process the runner executes.
+
+## Process & Artifacts
+
+- **Gate**: A deterministic check (lint, typecheck, test, determinism) run locally and/or in CI.
+- **Plan**: The resolved set of items to merge (eventually `plan.json`, schema-versioned).
+- **Stack**: User-authored prioritization/dependency hints (e.g., `.smartergpt/stack.yml`).
+- **Item**: A unit in the plan (often a PR).
+- **Integration branch**: Temporary branch used to weave/verify a batch of items before merging to `main`.
+
+## Repo Rules (Firm)
+
+- **Two-track separation**
+  - **Core runner** (`src/**`, CLI, MCP, packaging). **Never** store user/work artifacts.
+  - **`.smartergpt/**` = portable example profile only.
+    - **Track:** `intent.md`, `scope.yml`, `deps.yml`, `gates.yml`, `stack.yml`, `pull-request-template.md`
+    - **Ignore:** `.smartergpt/runner/`, `cache/`, `deliverables/` (deliverables are posted as PR comments, not committed).
+
+## Commit Style
+
+- Imperative mood: "Add…", "Fix…", "Update…"
+- Optional prefixes: `runner:`, `mcp:`, `schema:`, `tests:`, `ci:`, `docs:`, `workspace:`
+
+## Tagline (use verbatim)
+
+**Fan-out tasks as multiple PRs in parallel, then build a merge pyramid from the blocks. Compute dependency order, run gates locally, and merge cleanly.**