Initial project documentation and status

TODO.md

@@ -0,0 +1,95 @@
+# Task List
+
+## Discovery (Complete)
+
+- [x] Record MeshCentral version and deployment details.
+- [x] Identify whether MeshCentral is reachable only internally, through VPN, or via public ingress.
+- [x] Inventory current MeshCentral users, roles, device groups, and test endpoints.
+- [x] Select one non-production test device.
+- [x] Confirm where secrets and bridge logs may be stored.
+- [x] Research the supported MeshCentral API/server integration options.
+- [x] Check for maintained open-source adapters before building custom code.
+
+## Design (Complete)
+
+- [x] Choose bridge deployment location.
+- [x] Define trust boundaries and network flows.
+- [x] Define typed read-only tool contracts.
+- [x] Define authentication, authorization, target allowlists, and audit-log format.
+- [x] Define timeout, output-size, retry, and concurrency behavior.
+- [x] Define prompt-injection handling for endpoint output.
+
+## Build (Complete)
+
+- [x] Implement connectivity/authentication proof of concept.
+- [x] Implement device/group inventory.
+- [x] Implement status and metadata retrieval.
+- [x] Implement structured errors and health endpoint.
+- [x] Add unit/integration tests using the selected test device or a mock server.
+- [x] Add deployment and rollback documentation.
+
+## Security Hardening (Complete)
+
+- [x] Implement bounded request concurrency with safe defaults (5 concurrent requests).
+- [x] Implement rate limiting using token bucket algorithm.
+- [x] Add structured audit logging with automatic secret redaction.
+- [x] Validate credentials before use (username format, password length).
+- [x] Redact secrets in logs (base64, hex, known key patterns).
+- [x] Enforce device/group allowlists for target protection.
+- [x] Add bounded response size validation (1 MB max).
+- [x] Implement protocol schema validation with Zod.
+
+## Verification Status (Complete)
+
+- [x] Test suite passes: 90/90 tests
+- [x] TypeScript build passes with no errors
+- [x] ESLint passes with no warnings
+- [x] Security review findings reconciled in `review/FINAL-HARDENING-REVIEW.md`
+
+## Remaining Live-Test Gates
+
+### Pre-Live Requirements (Must Complete Before Any Live Test)
+
+1. **Security Review Address Findings**
+   - [x] Review findings in `review/LIVE-ADAPTER-REVIEW.md` reconciled against the current source
+   - [x] Address or accept all high-severity findings
+   - [x] Document risk acceptance for deferred non-blocking items in `review/FINAL-HARDENING-REVIEW.md`
+
+2. **Live-Test Checklist (See DEPLOYMENT.md)**
+   - [ ] Confirm mesh.ledrew.me resolves to intended MeshCentral instance
+   - [ ] Verify control.ashx WebSocket endpoint availability
+   - [ ] Confirm sa_clawdia has read-only permissions only
+   - [ ] Verify PVE3 is the sole allowlisted test target
+   - [ ] Test secret retrieval mechanism (no credentials in code/logs)
+   - [ ] Verify audit logging captures all security events
+
+3. **Explicit Approval**
+   - [x] Rob's project-level authorization for read-only live access (2026-08-26)
+   - [ ] No credentials stored in prompts, commands, or logs
+
+### Deployment/ Rollback Checklist
+
+**Deployment:**
+1. Deploy bridge to host with restricted firewall (outbound only to mesh.ledrew.me:80)
+2. Configure runtime secrets via protected environment file (mode 0600)
+3. Start bridge service with audit logging enabled
+4. Verify health endpoint returns healthy=true
+
+**Rollback:**
+1. Stop bridge service
+2. Rotate integration credential in MeshCentral immediately
+3. Review audit logs for unauthorized access patterns
+4. Document incident if rollback was due to failure
+
+## Later (Only After Security Review)
+
+- [ ] Add allowlisted diagnostics.
+- [ ] Add explicit confirmation flow for reversible actions.
+- [ ] Add dry-run support.
+- [ ] Add idempotency and duplicate-execution protection.
+
+## Not Approved
+
+- [ ] Enable remote commands or state-changing actions
+- [ ] Connect to PVE1/PVE2 production cluster
+- [ ] Expose bridge or MeshCentral to public internet