Auto-sync .kiro/ from master (post-checkout hook)

2026-05-13 14:22:04 -06:00
parent b43e1c5037
commit 0d58b3fd25
6 changed files with 826 additions and 52 deletions
--- a/.kiro/specs/config-wizard/design.md
+++ b/.kiro/specs/config-wizard/design.md
@@ -0,0 +1,486 @@
+# Design Document: Config Wizard
+
+## Overview
+
+The Config Wizard is a single-file Node.js CLI script (`configure.js`) at the project root that interactively guides deployers through configuring all environment variables for the CVE Dashboard. It replaces the manual process of copying `.env.example` and editing values by hand.
+
+The wizard uses only the Node.js built-in `readline` module — no external dependencies. It writes two output files: `backend/.env` and `frontend/.env`. It derives smart defaults by parsing `docker-compose.yml` for Postgres credentials and propagates the backend PORT into frontend URL defaults.
+
+Key design goals:
+- Zero dependencies beyond Node.js 18+ standard library
+- Single file implementation for easy maintenance
+- Idempotent re-runs that preserve existing values and unmanaged variables
+- Group-based flow with skip capability for unused integrations
+
+## Architecture
+
+The wizard follows a linear pipeline architecture:
+
+```mermaid
+flowchart TD
+    A[Start: node configure.js] --> B[Validate project root]
+    B --> C[Parse existing .env files]
+    C --> D[Parse docker-compose.yml for defaults]
+    D --> E[Display welcome message]
+    E --> F[Group loop: prompt variables]
+    F --> G[Display summary]
+    G --> H{User confirms?}
+    H -->|Yes| I[Handle existing file backup/overwrite]
+    I --> J[Write backend/.env]
+    J --> K[Write frontend/.env]
+    K --> L[Display success + next steps]
+    H -->|No| M{Restart or exit?}
+    M -->|Restart| E
+    M -->|Exit| N[Exit code 1]
+    B -->|Missing dirs| O[Error + exit code 1]
+```
+
+### Execution Flow
+
+1. **Validation** — Confirm `backend/` and `frontend/` directories exist relative to CWD
+2. **Parse existing** — Read current `backend/.env` and `frontend/.env` if they exist, extract key-value pairs
+3. **Parse docker-compose** — Extract Postgres credentials from `docker-compose.yml` using line-by-line parsing
+4. **Welcome** — Display purpose and instructions
+5. **Group loop** — Iterate through variable groups in order, prompting for each variable
+6. **Summary** — Display all configured values (sensitive ones masked) and target file paths
+7. **Confirmation** — User approves or rejects; rejection offers restart or exit
+8. **Write** — Generate env file content and write to disk with backup handling
+
+### Signal Handling
+
+A `SIGINT` handler (Ctrl+C) is registered at startup. When triggered:
+- Close the readline interface
+- Print a cancellation message
+- Exit with code 1
+- No files are written regardless of progress
+
+## Components and Interfaces
+
+### Module Structure
+
+All code lives in a single `configure.js` file organized into these logical sections:
+
+```
+configure.js
+├── Constants & Configuration
+│   ├── VARIABLE_DESCRIPTORS[]     — metadata for all managed variables
+│   ├── GROUP_ORDER[]              — ordered list of group names
+│   ├── GROUP_DESCRIPTIONS{}       — one-line description per group
+│   └── SENSITIVE_VARS[]           — list of variable names to mask
+├── Parsing Functions
+│   ├── parseEnvFile(filePath)     — read existing .env into key-value map
+│   ├── parseDockerCompose(filePath) — extract Postgres config
+│   └── resolveShellDefault(str)   — extract default from ${VAR:-default} syntax
+├── Validation Functions
+│   ├── validatePort(value)
+│   ├── validateCorsOrigins(value)
+│   ├── validateDatabaseUrl(value)
+│   ├── validateSessionSecret(value)
+│   └── validateRequired(value)
+├── Display Functions
+│   ├── printWelcome()
+│   ├── printGroupHeader(group)
+│   ├── printSummary(config, skippedGroups)
+│   └── maskSensitive(name, value)
+├── Prompt Functions
+│   ├── promptVariable(rl, descriptor, currentValue)
+│   ├── promptYesNo(rl, question, defaultNo)
+│   └── promptOverwrite(rl, filePath)
+├── File Writing
+│   ├── generateEnvContent(variables, groups)
+│   ├── writeEnvFile(filePath, content)
+│   └── createBackup(filePath)
+└── Main Flow
+    └── main()
+```
+
+### Key Interfaces
+
+#### Variable Descriptor
+
+```javascript
+{
+  name: String,           // e.g. "PORT"
+  group: String,          // e.g. "Core Settings"
+  required: Boolean,      // true = must have a value
+  default: String|null,   // factory default value
+  description: String,    // max 120 chars
+  docUrl: String|null,    // URL for obtaining the value
+  sensitive: Boolean,     // true = mask in display
+  validator: String|null  // name of validation function to apply
+}
+```
+
+#### Parsed Config State
+
+```javascript
+{
+  values: Map<String, String>,       // variable name → entered value
+  skippedGroups: Set<String>,        // groups the user declined
+  existingBackend: Map<String, String>,  // parsed from existing backend/.env
+  existingFrontend: Map<String, String>, // parsed from existing frontend/.env
+  unmanagedBackend: String[],        // lines not matching managed vars
+  unmanagedFrontend: String[],       // lines not matching managed vars
+  derivedDefaults: {                 // computed from docker-compose/port
+    DATABASE_URL: String|null,
+    databaseUrlSource: 'compose'|'fallback',
+    REACT_APP_API_BASE: String|null,
+    CORS_ORIGINS: String|null
+  }
+}
+```
+
+#### parseEnvFile(filePath) → { managed: Map, unmanaged: String[] }
+
+Reads a `.env` file line by line. For each non-empty, non-comment line, splits on the first `=` character. If the key matches a managed variable, stores it in `managed`. Otherwise, preserves the raw line (including preceding comments) in `unmanaged`.
+
+#### parseDockerCompose(filePath) → { user, password, database, port } | null
+
+Line-by-line parser that extracts:
+- `POSTGRES_USER` from `POSTGRES_USER: value` or `POSTGRES_USER: ${VAR:-default}`
+- `POSTGRES_PASSWORD` from `POSTGRES_PASSWORD: ${VAR:-default}` (resolves the default)
+- `POSTGRES_DB` from `POSTGRES_DB: value`
+- Host port from `- "host:container"` under the `ports:` key
+
+Returns `null` if the file doesn't exist or can't be parsed.
+
+#### generateEnvContent(variables, groupOrder, groupDescriptions) → String
+
+Produces the final `.env` file content:
+- Group header comments (`# --- Group Name ---`)
+- `KEY=value` lines, with values containing spaces/`#`/quotes wrapped in double quotes
+- Omits optional variables with no value
+- Appends unmanaged variables in a `# Custom Variables` section
+
+## Data Models
+
+### Variable Descriptor Registry
+
+The complete list of managed variables with their metadata:
+
+| Name | Group | Required | Default | Sensitive | Validator |
+|------|-------|----------|---------|-----------|-----------|
+| `PORT` | Core Settings | yes | `3001` | no | `validatePort` |
+| `API_HOST` | Core Settings | yes | `localhost` | no | — |
+| `CORS_ORIGINS` | Core Settings | yes | (derived) | no | `validateCorsOrigins` |
+| `DATABASE_URL` | Database | yes | (derived) | yes | `validateDatabaseUrl` |
+| `SESSION_SECRET` | Session | yes | — | yes | `validateSessionSecret` |
+| `NVD_API_KEY` | NVD API | no | — | yes | — |
+| `IVANTI_API_KEY` | Ivanti Integration | no | — | yes | — |
+| `IVANTI_CLIENT_ID` | Ivanti Integration | no | `1550` | no | — |
+| `IVANTI_FIRST_NAME` | Ivanti Integration | no | — | no | — |
+| `IVANTI_LAST_NAME` | Ivanti Integration | no | — | no | — |
+| `IVANTI_BU_FILTER` | Ivanti Integration | no | `NTS-AEO-ACCESS-ENG,NTS-AEO-STEAM` | no | — |
+| `IVANTI_MANAGED_BUS` | Ivanti Integration | no | `NTS-AEO-ACCESS-ENG,NTS-AEO-STEAM` | no | — |
+| `IVANTI_SKIP_TLS` | Ivanti Integration | no | `false` | no | — |
+| `ATLAS_API_URL` | Atlas Integration | no | — | no | — |
+| `ATLAS_API_USER` | Atlas Integration | no | — | no | — |
+| `ATLAS_API_PASS` | Atlas Integration | no | — | yes | — |
+| `ATLAS_SKIP_TLS` | Atlas Integration | no | `false` | no | — |
+| `JIRA_BASE_URL` | Jira Integration | no | — | no | — |
+| `JIRA_AUTH_METHOD` | Jira Integration | no | `basic` | no | — |
+| `JIRA_API_USER` | Jira Integration | no | — | no | — |
+| `JIRA_API_TOKEN` | Jira Integration | no | — | yes | — |
+| `JIRA_PAT` | Jira Integration | no | — | yes | — |
+| `JIRA_PROJECT_KEY` | Jira Integration | no | — | no | — |
+| `JIRA_ISSUE_TYPE` | Jira Integration | no | `Task` | no | — |
+| `JIRA_SKIP_TLS` | Jira Integration | no | `false` | no | — |
+| `CARD_API_URL` | CARD Integration | no | — | no | — |
+| `CARD_API_USER` | CARD Integration | no | — | no | — |
+| `CARD_API_PASS` | CARD Integration | no | — | yes | — |
+| `CARD_SKIP_TLS` | CARD Integration | no | `false` | no | — |
+| `GITLAB_URL` | GitLab Integration | no | `http://steam-gitlab.charterlab.com` | no | — |
+| `GITLAB_PROJECT_ID` | GitLab Integration | no | — | no | — |
+| `GITLAB_PAT` | GitLab Integration | no | — | yes | — |
+| `REACT_APP_API_BASE` | Frontend Settings | yes | (derived) | no | — |
+| `REACT_APP_API_HOST` | Frontend Settings | yes | (derived) | no | — |
+
+### Group Order and Descriptions
+
+```javascript
+const GROUP_ORDER = [
+  'Core Settings',
+  'Database',
+  'Session',
+  'NVD API',
+  'Ivanti Integration',
+  'Atlas Integration',
+  'Jira Integration',
+  'CARD Integration',
+  'GitLab Integration',
+  'Frontend Settings'
+];
+
+const GROUP_DESCRIPTIONS = {
+  'Core Settings': 'Server port, hostname, and CORS configuration',
+  'Database': 'PostgreSQL connection string for persistent storage',
+  'Session': 'Secret key for signing session cookies',
+  'NVD API': 'National Vulnerability Database API key for CVE lookups',
+  'Ivanti Integration': 'RiskSense platform credentials for vulnerability sync',
+  'Atlas Integration': 'Atlas InfoSec API for action plan management',
+  'Jira Integration': 'Jira Data Center for ticket creation and tracking',
+  'CARD Integration': 'CARD asset ownership API for host lookups',
+  'GitLab Integration': 'GitLab API for feedback submission (bug reports)',
+  'Frontend Settings': 'React app API endpoint configuration'
+};
+```
+
+### Optional (Skippable) Groups
+
+Groups that present a skip prompt before entering: `NVD API`, `Ivanti Integration`, `Atlas Integration`, `Jira Integration`, `CARD Integration`, `GitLab Integration`.
+
+Core Settings, Database, Session, and Frontend Settings are always prompted.
+
+### Docker-Compose Parsing Approach
+
+The parser reads `docker-compose.yml` line by line without a full YAML parser. It uses a simple state machine:
+
+1. **Find service** — Look for a line matching `postgres:` (indented under `services:`)
+2. **Find environment** — Within the postgres service block, look for `environment:`
+3. **Extract vars** — Read `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` values
+4. **Find ports** — Look for `ports:` within the postgres service block
+5. **Extract host port** — Parse `- "host:container"` to get the host port (left side)
+
+Shell variable substitution (`${VAR:-default}`) is resolved by extracting the default value after `:-`.
+
+```javascript
+function resolveShellDefault(value) {
+  const match = value.match(/\$\{[^:}]+:-([^}]+)\}/);
+  return match ? match[1] : value;
+}
+```
+
+If parsing fails at any step, the function returns `null` and the caller falls back to the hardcoded default: `postgresql://steam:sV4xmC9xAUCFop0ypxMVS056QgPqGrX@localhost:5433/cve_dashboard`.
+
+### Env File Output Format
+
+```
+# --- Core Settings ---
+PORT=3001
+API_HOST=localhost
+CORS_ORIGINS=http://localhost:3000
+
+# --- Database ---
+DATABASE_URL=postgresql://steam:sV4xmC9xAUCFop0ypxMVS056QgPqGrX@localhost:5433/cve_dashboard
+
+# --- Session ---
+SESSION_SECRET=my-very-long-secret-key-here
+
+# --- Custom Variables ---
+MY_CUSTOM_VAR=preserved_value
+```
+
+Values containing spaces, `#`, or quote characters are wrapped in double quotes:
+```
+SOME_VAR="value with spaces"
+ANOTHER_VAR="value#with#hashes"
+```
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: Descriptor registry invariants
+
+*For any* variable descriptor in the registry, the variable name must appear exactly once across all groups, and the group description must be non-empty and at most 120 characters long.
+
+**Validates: Requirements 2.3, 2.5**
+
+### Property 2: Variable ordering within groups
+
+*For any* Variable_Group, all required variables in that group must appear before all optional variables in the descriptor list ordering.
+
+**Validates: Requirements 2.4**
+
+### Property 3: Group presentation order
+
+*For any* two consecutive variables in the descriptor list, the first variable's group index in GROUP_ORDER must be less than or equal to the second variable's group index.
+
+**Validates: Requirements 2.1**
+
+### Property 4: Sensitive value masking
+
+*For any* string value longer than 8 characters, `maskSensitive` should return a string showing only the first 4 and last 4 characters with asterisks in between. *For any* string value of 8 characters or fewer, `maskSensitive` should return the full value unchanged.
+
+**Validates: Requirements 3.4**
+
+### Property 5: Shell variable default resolution
+
+*For any* string containing the pattern `${VARNAME:-defaultvalue}`, `resolveShellDefault` should extract and return `defaultvalue`. *For any* string not containing that pattern, it should return the original string.
+
+**Validates: Requirements 4.1**
+
+### Property 6: DATABASE_URL construction
+
+*For any* valid Postgres credentials tuple (user, password, port, database) where port is an integer in [1, 65535], the constructed DATABASE_URL should equal `postgresql://{user}:{password}@localhost:{port}/{database}`.
+
+**Validates: Requirements 4.2**
+
+### Property 7: Derived URL defaults from PORT
+
+*For any* valid port number P, the derived `REACT_APP_API_BASE` should equal `http://localhost:{P}/api`, `REACT_APP_API_HOST` should equal `http://localhost:{P}`, and `CORS_ORIGINS` should equal `http://localhost:3000`.
+
+**Validates: Requirements 4.6**
+
+### Property 8: Port validation
+
+*For any* string input, `validatePort` should return true if and only if the trimmed value is a string representation of an integer in the range [1, 65535].
+
+**Validates: Requirements 5.2**
+
+### Property 9: CORS origins validation
+
+*For any* comma-separated string, `validateCorsOrigins` should return true if and only if every trimmed entry starts with `http://` or `https://`.
+
+**Validates: Requirements 5.3**
+
+### Property 10: DATABASE_URL validation
+
+*For any* string, `validateDatabaseUrl` should return true if and only if the string starts with `postgresql://` or equals the literal string `sqlite`.
+
+**Validates: Requirements 5.4**
+
+### Property 11: SESSION_SECRET validation
+
+*For any* string, `validateSessionSecret` should return true if and only if its length is at least 16 characters.
+
+**Validates: Requirements 5.6**
+
+### Property 12: Required variable rejection of whitespace
+
+*For any* string composed entirely of whitespace characters (including empty string), `validateRequired` should return false.
+
+**Validates: Requirements 5.1**
+
+### Property 13: Env value quoting
+
+*For any* key-value pair, `generateEnvContent` should wrap the value in double quotes if and only if the value contains a space, `#`, or quote character. Values without those characters should appear unquoted.
+
+**Validates: Requirements 6.3**
+
+### Property 14: Optional variable omission
+
+*For any* optional variable descriptor with no user-provided value and no default value, `generateEnvContent` should not include a line for that variable in the output.
+
+**Validates: Requirements 6.4**
+
+### Property 15: Skipped group exclusion
+
+*For any* Variable_Group that the user declines, the generated env file content should contain no `KEY=value` lines for any variable belonging to that group.
+
+**Validates: Requirements 7.2, 7.3**
+
+### Property 16: Env file round-trip parsing
+
+*For any* valid env file content produced by `generateEnvContent`, parsing it with `parseEnvFile` should recover all the original key-value pairs for managed variables.
+
+**Validates: Requirements 9.1, 9.2**
+
+### Property 17: Unmanaged variable preservation
+
+*For any* existing env file containing lines with keys not in the managed variable list, those lines should appear unchanged in the "Custom Variables" section of the generated output.
+
+**Validates: Requirements 9.4**
+
+### Property 18: Managed key deduplication
+
+*For any* managed variable name that appears both in the wizard-entered values and in the unmanaged lines parsed from an existing file, the generated output should contain exactly one occurrence of that key, using the wizard-entered value.
+
+**Validates: Requirements 9.5**
+
+## Error Handling
+
+### Categories
+
+| Error Type | Handling Strategy |
+|---|---|
+| Missing project structure | Print error to stderr, exit code 1 |
+| SIGINT (Ctrl+C) | Close readline, print cancellation, exit code 1, no files written |
+| Invalid user input | Display format error, re-prompt same variable |
+| Docker-compose parse failure | Log warning, fall back to hardcoded defaults |
+| Existing env file unreadable | Log warning, use factory defaults, preserve file as backup |
+| File write failure | Print error with path and reason, exit immediately without writing remaining files |
+| Overwrite declined | Skip that file, continue with other files |
+
+### Error Messages
+
+All error messages follow the pattern: `Error: {what went wrong}. {what to do about it}.`
+
+Examples:
+- `Error: This script must be run from the project root (backend/ and frontend/ directories not found). Run from the directory containing both folders.`
+- `Error: PORT must be an integer between 1 and 65535.`
+- `Error: Could not write to backend/.env (Permission denied). Check file permissions and try again.`
+
+### Graceful Degradation
+
+The wizard degrades gracefully when optional infrastructure is missing:
+- No `docker-compose.yml` → uses hardcoded DATABASE_URL default
+- Malformed `docker-compose.yml` → warns and uses hardcoded default
+- Existing `.env` unreadable → warns, backs up, uses factory defaults
+- No existing `.env` files → normal first-run behavior
+
+## Testing Strategy
+
+### Unit Tests
+
+Unit tests cover the pure functions in isolation:
+
+- `resolveShellDefault()` — various `${VAR:-default}` patterns
+- `parseDockerCompose()` — valid compose files, missing files, malformed content
+- `parseEnvFile()` — standard files, quoted values, comments, empty lines, malformed lines
+- `validatePort()` — boundary values (0, 1, 65535, 65536), non-numeric, floats
+- `validateCorsOrigins()` — single/multiple origins, invalid schemes, whitespace
+- `validateDatabaseUrl()` — postgresql://, sqlite, invalid prefixes
+- `validateSessionSecret()` — boundary at 15/16 characters
+- `validateRequired()` — empty, whitespace-only, valid values
+- `maskSensitive()` — short values (≤8), long values, exact boundary (8, 9 chars)
+- `generateEnvContent()` — quoting rules, group headers, omission of empty optionals
+
+### Property-Based Tests
+
+Property-based tests use [fast-check](https://github.com/dubzzz/fast-check) to verify universal properties across generated inputs. Each property test runs a minimum of 100 iterations.
+
+Tests are tagged with: `Feature: config-wizard, Property {N}: {title}`
+
+Properties to implement:
+1. Descriptor registry invariants (uniqueness, description length)
+2. Variable ordering within groups (required before optional)
+3. Group presentation order (monotonic group index)
+4. Sensitive value masking (length-based behavior)
+5. Shell variable default resolution (pattern extraction)
+6. DATABASE_URL construction (format correctness)
+7. Derived URL defaults from PORT (format correctness)
+8. Port validation (range check)
+9. CORS origins validation (scheme check)
+10. DATABASE_URL validation (prefix check)
+11. SESSION_SECRET validation (length check)
+12. Required variable rejection of whitespace
+13. Env value quoting (conditional wrapping)
+14. Optional variable omission
+15. Skipped group exclusion
+16. Env file round-trip parsing
+17. Unmanaged variable preservation
+18. Managed key deduplication
+
+### Integration Tests
+
+Integration tests verify end-to-end flows using a temporary directory:
+
+- Full wizard run with all defaults accepted → correct files written
+- Wizard run with existing `.env` files → values pre-filled correctly
+- Wizard run with skipped groups → those groups absent from output
+- SIGINT at various points → no files written
+- Missing project structure → error exit
+- File write permission error → graceful failure
+
+### Test Runner
+
+Tests use Jest (already configured in the project via `react-scripts test` for frontend). Backend tests run with:
+
+```bash
+cd backend
+npx jest __tests__/config-wizard*.test.js
+```
+
+Property tests use `fast-check` as the generator library within Jest test cases.
+