meshcentral-openclaw-bridge/TODO.md

Task List

Discovery (Complete)

• Record MeshCentral version and deployment details.
• Identify whether MeshCentral is reachable only internally, through VPN, or via public ingress.
• Inventory current MeshCentral users, roles, device groups, and test endpoints.
• Select one non-production test device.
• Confirm where secrets and bridge logs may be stored.
• Research the supported MeshCentral API/server integration options.
• Check for maintained open-source adapters before building custom code.

Design (Complete)

• Choose bridge deployment location.
• Define trust boundaries and network flows.
• Define typed read-only tool contracts.
• Define authentication, authorization, target allowlists, and audit-log format.
• Define timeout, output-size, retry, and concurrency behavior.
• Define prompt-injection handling for endpoint output.

Build (Complete)

• Implement connectivity/authentication proof of concept.
• Implement device/group inventory.
• Implement status and metadata retrieval.
• Implement structured errors and health endpoint.
• Add unit/integration tests using the selected test device or a mock server.
• Add deployment and rollback documentation.

Security Hardening (Complete)

• Implement bounded request concurrency with safe defaults (5 concurrent requests).
• Implement rate limiting using token bucket algorithm.
• Add structured audit logging with automatic secret redaction.
• Validate credentials before use (username format, password length).
• Redact secrets in logs (base64, hex, known key patterns).
• Enforce device/group allowlists for target protection.
• Add bounded response size validation (1 MB max).
• Implement protocol schema validation with Zod.

Verification Status (Complete)

• Test suite passes: 91/91 tests
• TypeScript build passes with no errors
• ESLint passes with no warnings
• Security review findings reconciled in review/FINAL-HARDENING-REVIEW.md

Live Verification (Complete)

• mesh.ledrew.me resolves to the intended MeshCentral endpoint
• TLS validation and /control.ashx WSS upgrade verified
• sa_clawdia authenticated successfully with the protected credential file
• Servers group inventory returned successfully
• PVE3 was found in the Servers group
• Real adapter mapped the live node correctly
• No credentials, tokens, commands, diagnostics, or state-changing operations were exposed or performed

The live probe uses the upstream-compatible transport in implementation/src/upstream-transport.ts. MeshCentral's serverversion action is not used as the least-privilege health check because it requires server-upgrade capability; authenticated meshes inventory is the health check instead.

Remaining Deployment/Review Work

1. Review the uncommitted diff and commit on a feature branch.
2. Complete an independent final security review against the newly integrated transport.
3. Complete deployment/rollback documentation for a future non-production deployment.
4. Add an OpenClaw-facing tool/MCP wrapper only after the read-only adapter contract is finalized.

Deployment:

1. Deploy bridge to an approved trusted host with restricted firewall (outbound only to the MeshCentral endpoint)
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