Initial project documentation and status
This commit is contained in:
Clawdia
@@ -0,0 +1,39 @@
|
|||||||
|
# Architecture decision record
|
||||||
|
|
||||||
|
## ADR-0001 — Begin with a read-only integration
|
||||||
|
|
||||||
|
**Status:** Accepted
|
||||||
|
**Date:** 2026-08-24
|
||||||
|
|
||||||
|
### Decision
|
||||||
|
|
||||||
|
The first milestone will expose only device inventory, status, and safe metadata. Remote command execution and state-changing actions will not be part of the initial MVP.
|
||||||
|
|
||||||
|
### Rationale
|
||||||
|
|
||||||
|
This validates connectivity, authentication, data mapping, logging, and OpenClaw tool behavior while minimizing the blast radius of implementation mistakes.
|
||||||
|
|
||||||
|
### Consequences
|
||||||
|
|
||||||
|
- Initial usefulness is limited to visibility and reporting.
|
||||||
|
- Diagnostics require a later, separately reviewed capability.
|
||||||
|
- The bridge can be tested without risking endpoint changes.
|
||||||
|
|
||||||
|
## ADR-0002 — Prefer a local bridge over browser automation
|
||||||
|
|
||||||
|
**Status:** Proposed
|
||||||
|
**Date:** 2026-08-24
|
||||||
|
|
||||||
|
### Decision
|
||||||
|
|
||||||
|
Investigate a local API/MCP-style bridge first. Browser automation remains a fallback for discovery or occasional operations, not the primary architecture.
|
||||||
|
|
||||||
|
### Rationale
|
||||||
|
|
||||||
|
A typed local interface is easier to constrain, test, audit, and maintain than UI selectors and browser sessions.
|
||||||
|
|
||||||
|
### Open questions
|
||||||
|
|
||||||
|
- What supported MeshCentral API surface is available in the deployed version?
|
||||||
|
- Should the bridge run in the MeshCentral LXC, a separate LXC, or on ledclaw01?
|
||||||
|
- Which OpenClaw integration mechanism best fits the final tool contract?
|
||||||
@@ -0,0 +1,41 @@
|
|||||||
|
# Deployment facts and live-test plan
|
||||||
|
|
||||||
|
## MeshCentral deployment
|
||||||
|
|
||||||
|
- Hostname: `mesh.ledrew.me`
|
||||||
|
- Internal address: `10.10.10.177:80`
|
||||||
|
- Reported version: `1.2.5`
|
||||||
|
- Location: LXC on PVE2
|
||||||
|
- Installation method: Proxmox Community Scripts MeshCentral installer
|
||||||
|
- Test endpoint: `PVE3`
|
||||||
|
- Integration account: `sa_clawdia`
|
||||||
|
|
||||||
|
## Secret handling
|
||||||
|
|
||||||
|
The integration password was provided out-of-band in the project conversation and is intentionally **not stored in this repository, project files, logs, command lines, or agent prompts**. The real adapter must receive it through a protected runtime secret mechanism, such as a root-readable `0600` environment file or equivalent secret store.
|
||||||
|
|
||||||
|
If the credential is ever committed, logged, pasted into a command, or exposed to an unintended audience, rotate it immediately in MeshCentral.
|
||||||
|
|
||||||
|
## Live-test prerequisites
|
||||||
|
|
||||||
|
Before connecting:
|
||||||
|
|
||||||
|
- Confirm that `mesh.ledrew.me` is intended to resolve/reach the internal MeshCentral service from the proposed bridge host.
|
||||||
|
- Determine whether the reported port 80 is plain HTTP behind a reverse proxy and whether the MeshCentral control channel is available at the corresponding `/control.ashx` WebSocket endpoint.
|
||||||
|
- Verify the certificate/trust path if the control channel uses TLS; never disable certificate validation.
|
||||||
|
- Confirm `sa_clawdia` has only the required read-only permissions for the first test.
|
||||||
|
- Confirm `PVE3` is the sole target allowlisted for the first live test.
|
||||||
|
- Use only read-only operations: authentication/health check, server version, device groups, device inventory, and selected device metadata.
|
||||||
|
- Capture no password or session token in logs.
|
||||||
|
|
||||||
|
## Security Hardening Status
|
||||||
|
|
||||||
|
- **Concurrency & Rate Limits**: 5 concurrent requests max; token-bucket rate limiter applied to all outbound requests.
|
||||||
|
- **Audit Redaction**: Structured audit logs automatically redact secrets (base64, hex, known key patterns) and never capture credentials.
|
||||||
|
- **Verification**: 90/90 tests pass; TypeScript build passes with no errors; ESLint passes with no warnings.
|
||||||
|
- **Remaining Live-Test Gates**: See TODO.md for the operational checklist. Rob authorized read-only project access on 2026-08-26; no additional per-test approval is required, but all scope and stop conditions remain mandatory.
|
||||||
|
- **Rollback Rules**: If rollback is required: stop service immediately, rotate integration credential in MeshCentral, review audit logs, and document incident.
|
||||||
|
|
||||||
|
## Authorization checkpoint
|
||||||
|
|
||||||
|
A live connectivity test is authorized under Rob's project-level read-only access decision on 2026-08-26. The authorization covers only the documented read-only operations and PVE3 target; it does not cover commands, diagnostics, or state changes.
|
||||||
@@ -0,0 +1,57 @@
|
|||||||
|
# Read-Only MeshCentral Live-Test Procedure
|
||||||
|
|
||||||
|
**Status:** Prepared and authorized for execution under the project scope
|
||||||
|
**Authorization:** Rob authorized read-only MeshCentral access for this project on 2026-08-26.
|
||||||
|
|
||||||
|
## Preconditions
|
||||||
|
|
||||||
|
Do not proceed unless all are confirmed:
|
||||||
|
|
||||||
|
- The bridge runs from an approved trusted management host.
|
||||||
|
- `mesh.ledrew.me` resolves to the intended internal MeshCentral instance.
|
||||||
|
- The control channel is the intended `/control.ashx` WebSocket endpoint.
|
||||||
|
- TLS certificate validation succeeds from the bridge host, or an approved private CA bundle is configured. Never disable verification.
|
||||||
|
- `sa_clawdia` is a dedicated read-only integration account.
|
||||||
|
- The exact PVE3 device ID/group is known and is the only configured target allowlist entry.
|
||||||
|
- The password is available only through a protected runtime secret mechanism (for example a `0600` environment file); it is not placed in source, prompts, command arguments, or logs.
|
||||||
|
- Audit-log destination and permissions are confirmed.
|
||||||
|
- Local verification has passed: tests, build, and lint.
|
||||||
|
|
||||||
|
## Allowed operations
|
||||||
|
|
||||||
|
Only these read-only operations may be used:
|
||||||
|
|
||||||
|
1. Connect/authenticate and perform the health/connectivity check.
|
||||||
|
2. Query MeshCentral server version.
|
||||||
|
3. List device groups.
|
||||||
|
4. List devices, filtered to the approved scope.
|
||||||
|
5. Retrieve metadata for the single approved PVE3 target.
|
||||||
|
|
||||||
|
Do not request events, diagnostics, commands, shell access, file transfer, power operations, user/group changes, reboots, shutdowns, or any state-changing operation.
|
||||||
|
|
||||||
|
## Execution checklist
|
||||||
|
|
||||||
|
1. Record the test start time and the approved target identifier without recording secrets.
|
||||||
|
2. Load the protected runtime secret without echoing it or placing it in the command line.
|
||||||
|
3. Run `npm run build`, then execute `npm run live-test`; the runner reads the protected credential file internally, uses the fixed MeshCentral endpoint/account, and has no target or operation CLI arguments.
|
||||||
|
4. The runner sends only server-version, device-group, and PVE3 inventory requests, one at a time.
|
||||||
|
5. Verify every result is scoped to the approved target and contains no unexpected credential/token material.
|
||||||
|
6. Confirm audit records contain operation, target, status, and timestamp, but no password, TOTP, auth header, session token, or raw sensitive output.
|
||||||
|
7. Disconnect cleanly.
|
||||||
|
8. Record pass/fail results, server version, target identifier, timestamps, and any non-secret error text.
|
||||||
|
|
||||||
|
## Stop conditions
|
||||||
|
|
||||||
|
Stop immediately and do not retry automatically if:
|
||||||
|
|
||||||
|
- TLS validation fails or the endpoint/path is unexpected.
|
||||||
|
- Authentication or authorization is unclear.
|
||||||
|
- The target cannot be resolved unambiguously to PVE3.
|
||||||
|
- Any operation would execute a command or change state.
|
||||||
|
- Output contains credentials, tokens, or unexpected sensitive data.
|
||||||
|
- The server response fails schema/action validation.
|
||||||
|
- The bridge attempts to contact any target outside the allowlist.
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
For a failed or ambiguous test: disconnect/stop the bridge, preserve non-secret logs, review audit records, and rotate the integration credential if exposure is suspected. Do not touch PVE1/PVE2 production infrastructure.
|
||||||
@@ -0,0 +1,50 @@
|
|||||||
|
{
|
||||||
|
"project": "meshcentral-openclaw-bridge",
|
||||||
|
"status": "blocked",
|
||||||
|
"worker": {
|
||||||
|
"taskName": "meshcentral-bridge-worker",
|
||||||
|
"sessionKey": null,
|
||||||
|
"runId": null,
|
||||||
|
"startedAt": "2026-08-26T14:59:00-04:00",
|
||||||
|
"lastActivityAt": "2026-08-26T19:13:07.576Z",
|
||||||
|
"lastMeaningfulChangeAt": "2026-08-26T14:53:00-04:00",
|
||||||
|
"pid": 139480
|
||||||
|
},
|
||||||
|
"currentTask": "Run local verification, then perform the bounded read-only compatibility probe.",
|
||||||
|
"completedMilestones": [
|
||||||
|
{
|
||||||
|
"task": "Added WebSocket cleanup-state instrumentation",
|
||||||
|
"completedAt": "2026-08-26T14:53:00-04:00"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"lastVerification": {
|
||||||
|
"tests": "passed",
|
||||||
|
"build": "passed",
|
||||||
|
"lint": "passed"
|
||||||
|
},
|
||||||
|
"liveTestFailures": 3,
|
||||||
|
"maxConsecutiveLiveTestFailures": 3,
|
||||||
|
"blocker": "Read-only live probe failed at the known safe stage; consecutive failures: 3.",
|
||||||
|
"nextAction": "Live testing stopped at the configured failure limit.",
|
||||||
|
"safety": {
|
||||||
|
"meshcentral": "read-only only",
|
||||||
|
"allowedOperations": [
|
||||||
|
"serverversion",
|
||||||
|
"meshes",
|
||||||
|
"nodes",
|
||||||
|
"deviceinfo"
|
||||||
|
],
|
||||||
|
"allowedTarget": "PVE3 only",
|
||||||
|
"prohibited": [
|
||||||
|
"commands",
|
||||||
|
"diagnostics",
|
||||||
|
"power operations",
|
||||||
|
"file transfer",
|
||||||
|
"administration",
|
||||||
|
"state changes",
|
||||||
|
"PVE1",
|
||||||
|
"PVE2"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"lastVerificationAt": "2026-08-26T19:12:36.937Z"
|
||||||
|
}
|
||||||
@@ -0,0 +1,226 @@
|
|||||||
|
# MeshCentral ↔ OpenClaw Bridge — Complete Project Status
|
||||||
|
|
||||||
|
**Snapshot:** 2026-08-25 22:17 EDT (America/Toronto)
|
||||||
|
**Owner:** Rob
|
||||||
|
**Project manager:** Clawdia
|
||||||
|
**Project path:** `/home/ledadmin/projects/meshcentral-openclaw-bridge`
|
||||||
|
**Current state:** ACTIVE — local protocol correction complete; live read-only verification pending
|
||||||
|
**Progress cron:** `meshcentral-project-progress` disabled at Rob's request at 21:57 EDT; resume only when Rob asks.
|
||||||
|
**Live-test gate:** CLOSED
|
||||||
|
|
||||||
|
## Executive summary
|
||||||
|
|
||||||
|
The local read-only MVP is implemented and passes its local verification gate. The bridge has not yet completed a successful live MeshCentral inventory test. A live test was attempted with Rob's explicit approval on 2026-08-25, successfully established the TLS/WebSocket connection, then MeshCentral closed the control session before accepting the first `serverversion` request. No inventory, device metadata, command, diagnostic execution, or state-changing action completed.
|
||||||
|
|
||||||
|
The exact MeshCentral 1.2.5 `meshctrl.js` protocol comparison is complete. The bridge was corrected to match the official authentication-header and response-correlation fields; local verification is green. The next task is a narrowly scoped live read-only compatibility test.
|
||||||
|
|
||||||
|
## Confirmed deployment facts
|
||||||
|
|
||||||
|
- MeshCentral public/reverse-proxy URL: `https://mesh.ledrew.me`
|
||||||
|
- MeshCentral backend: `10.10.10.177:80`
|
||||||
|
- MeshCentral version: `1.2.5`
|
||||||
|
- Installation: Proxmox Community Scripts MeshCentral installer
|
||||||
|
- MeshCentral location: LXC on PVE2
|
||||||
|
- Service: `meshcentral.service`
|
||||||
|
- Installation path: `/opt/meshcentral`
|
||||||
|
- Data path: `/opt/meshcentral/meshcentral-data`
|
||||||
|
- Test device: `PVE3` only
|
||||||
|
- MeshCentral group: `Servers`
|
||||||
|
- Integration username: `sa_clawdia`
|
||||||
|
- External WebSocket endpoint expected by bridge: `wss://mesh.ledrew.me/control.ashx`
|
||||||
|
- Reverse proxy: HTTPS enabled; WebSocket support reported enabled by Rob
|
||||||
|
- Account permissions selected by Rob:
|
||||||
|
- No New Device Groups
|
||||||
|
- No New Devices
|
||||||
|
- No Tools (MeshCmd/Router)
|
||||||
|
- Lock Account Settings
|
||||||
|
- No other listed permissions selected
|
||||||
|
|
||||||
|
### Secret handling
|
||||||
|
|
||||||
|
The password is stored outside the project at:
|
||||||
|
|
||||||
|
`/home/ledadmin/.openclaw/workspace/Credentials/.meshcentral-credentials`
|
||||||
|
|
||||||
|
The file was changed to mode `0600` during this work session. Its contents must never be copied into this project, prompts, command lines, logs, reports, or chat. Do not record the password in future project notes.
|
||||||
|
|
||||||
|
## Local implementation status
|
||||||
|
|
||||||
|
Location: `/home/ledadmin/projects/meshcentral-openclaw-bridge/implementation`
|
||||||
|
|
||||||
|
Implemented capabilities:
|
||||||
|
|
||||||
|
- Typed bridge contracts using Zod
|
||||||
|
- Mock adapter for offline development
|
||||||
|
- Real MeshCentral WebSocket adapter using `/control.ashx`
|
||||||
|
- `x-meshauth` credential encoding
|
||||||
|
- Credential validation before use
|
||||||
|
- Generic credential/configuration errors
|
||||||
|
- Credential and token redaction in structured logs
|
||||||
|
- Explicit TLS certificate validation (`rejectUnauthorized: true`)
|
||||||
|
- Optional custom CA configuration support in the client
|
||||||
|
- Bounded response size (`MAX_RESPONSE_SIZE`)
|
||||||
|
- JSON/protocol envelope validation
|
||||||
|
- Action-specific response schema validation
|
||||||
|
- Request/response action matching
|
||||||
|
- Device and group allowlist enforcement/filtering
|
||||||
|
- Timeout and bounded retry behavior
|
||||||
|
- Token-bucket rate limiting
|
||||||
|
- Bounded concurrent requests, safe default 5
|
||||||
|
- Configuration bounds validation for timeout, rate, burst, and concurrency
|
||||||
|
- Structured audit events and controlled logger integration
|
||||||
|
- Diagnostics remain mock-only
|
||||||
|
- No remote commands or state-changing actions are implemented
|
||||||
|
|
||||||
|
### Local verification evidence
|
||||||
|
|
||||||
|
Most recent successful verification during this session:
|
||||||
|
|
||||||
|
```text
|
||||||
|
npm test -- --runInBand
|
||||||
|
11 test suites passed
|
||||||
|
90 tests passed
|
||||||
|
|
||||||
|
npm run build
|
||||||
|
passed
|
||||||
|
|
||||||
|
npm run lint
|
||||||
|
passed with no errors or warnings
|
||||||
|
```
|
||||||
|
|
||||||
|
Generated `dist/` output was rebuilt repeatedly as part of verification. The project has no committed baseline; files are currently workspace files under the project directory.
|
||||||
|
|
||||||
|
## Security and review artifacts
|
||||||
|
|
||||||
|
Created/updated during this session:
|
||||||
|
|
||||||
|
- `review/FINAL-HARDENING-REVIEW.md`
|
||||||
|
- Current-source disposition of the older review findings
|
||||||
|
- Local MVP gate: PASS
|
||||||
|
- Live test: authorized by Rob for this project using the dedicated read-only account; operational scope remains strictly limited below
|
||||||
|
- Deferred timeout separation and reconnect behavior recorded as non-blocking only for a single read-only test
|
||||||
|
- `LIVE-TEST-PROCEDURE.md`
|
||||||
|
- Preconditions
|
||||||
|
- Allowed read-only operations
|
||||||
|
- Stop conditions
|
||||||
|
- Secret handling
|
||||||
|
- Audit checks
|
||||||
|
- Rollback procedure
|
||||||
|
- `DEPLOYMENT.md`
|
||||||
|
- Deployment facts
|
||||||
|
- Secret handling
|
||||||
|
- Live-test prerequisites
|
||||||
|
- Hardening summary
|
||||||
|
- Rollback rules
|
||||||
|
- `TODO.md`
|
||||||
|
- Local security review disposition marked complete
|
||||||
|
- Deployment-specific live-test gates remain open
|
||||||
|
|
||||||
|
Existing review artifacts:
|
||||||
|
|
||||||
|
- `review/REVIEW.md` — earlier implementation review; contains findings from before later hardening
|
||||||
|
- `review/LIVE-ADAPTER-REVIEW.md` — earlier live-adapter review; its findings were reconciled in `review/FINAL-HARDENING-REVIEW.md`
|
||||||
|
|
||||||
|
## Live test attempt and result
|
||||||
|
|
||||||
|
**Approval:** Rob authorized read-only MeshCentral access for this project on 2026-08-26. This replaces the prior per-test approval requirement. The authorization does not expand the operation or target scope.
|
||||||
|
|
||||||
|
The test used the protected external credential file and attempted only read-only operations:
|
||||||
|
|
||||||
|
- Connect/authenticate
|
||||||
|
- Health check / `serverversion`
|
||||||
|
- Intended follow-up: groups, inventory, PVE3 metadata
|
||||||
|
|
||||||
|
### Observed results
|
||||||
|
|
||||||
|
1. Direct WebSocket connection to `wss://mesh.ledrew.me/control.ashx` succeeded.
|
||||||
|
2. TLS certificate validation succeeded; this was not a basic network/TLS failure.
|
||||||
|
3. The server sent a MeshCentral protocol close message before accepting `serverversion`.
|
||||||
|
4. Bridge `healthCheck()` returned `false`.
|
||||||
|
5. A direct client diagnostic showed the socket opened, then the request failed as `Not connected` after the server-side close.
|
||||||
|
6. No groups, devices, PVE3 metadata, diagnostics, commands, or state changes were performed.
|
||||||
|
7. No password, auth header, cookie, or token was printed or logged.
|
||||||
|
|
||||||
|
A raw diagnostic observed a message shaped like:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"action":"close","cause":"<server value>","msg":"<server value>"}
|
||||||
|
```
|
||||||
|
|
||||||
|
The actual close values were not saved here because server-provided text may contain sensitive details. The server then closed with WebSocket code `1005` and no reason.
|
||||||
|
|
||||||
|
### Current hypothesis
|
||||||
|
|
||||||
|
Likely possibilities:
|
||||||
|
|
||||||
|
- MeshCentral 1.2.5 control-channel authentication/handshake sequence differs from the bridge implementation.
|
||||||
|
- The official client sends an initial message or uses a subtly different header/auth format.
|
||||||
|
- The reverse proxy accepts the WebSocket upgrade but affects the control protocol afterward.
|
||||||
|
- The restrictive account permissions may not permit the control-channel session/commands even though the connection authenticates at the WebSocket layer.
|
||||||
|
|
||||||
|
TLS and basic WebSocket reachability are less likely to be the primary failure because the handshake completed successfully.
|
||||||
|
|
||||||
|
## MeshCentral LXC evidence collected
|
||||||
|
|
||||||
|
Rob provided:
|
||||||
|
|
||||||
|
- `meshcentral.service` is active and running.
|
||||||
|
- Main process: `/usr/bin/node /opt/meshcentral/node_modules/meshcentral/meshcentral`
|
||||||
|
- Environment: `NODE_ENV=production`
|
||||||
|
- No debug flags in `ExecStart`
|
||||||
|
- Data files under `/opt/meshcentral/meshcentral-data`
|
||||||
|
- No normal log file was found by the provided search.
|
||||||
|
- `journalctl -u meshcentral.service` around the test window returned `-- No entries --`.
|
||||||
|
- The service is not currently emitting useful connection/authentication diagnostics at its present logging configuration.
|
||||||
|
|
||||||
|
No MeshCentral service configuration or debug setting was changed.
|
||||||
|
|
||||||
|
## Known blockers at pause
|
||||||
|
|
||||||
|
1. **Protocol comparison not started.** `PROTOCOL-COMPARISON.md` does not exist yet.
|
||||||
|
2. Need to compare the bridge with the exact MeshCentral 1.2.5 bundled `meshctrl.js` implementation, especially:
|
||||||
|
- `x-meshauth` construction
|
||||||
|
- WebSocket options and headers
|
||||||
|
- Any initial message after socket open
|
||||||
|
- First request framing and request IDs
|
||||||
|
- Handling of server `action: close`
|
||||||
|
- Permission behavior for inventory commands
|
||||||
|
3. Need to understand why the server closes the session before `serverversion`.
|
||||||
|
4. No successful live inventory test exists yet.
|
||||||
|
5. No current-source protocol compatibility test exists against a captured 1.2.5 fixture.
|
||||||
|
|
||||||
|
## Explicit safety boundaries
|
||||||
|
|
||||||
|
- Do not retry the live connection with commands or state-changing operations; the corrected client is limited to the documented read-only test plan.
|
||||||
|
- Do not run remote commands, diagnostics, shell access, file transfers, router operations, power operations, reboots, shutdowns, service changes, or any state-changing action.
|
||||||
|
- PVE1/PVE2 production cluster is off-limits.
|
||||||
|
- PVE3 is the only approved test target.
|
||||||
|
- Do not enable public exposure.
|
||||||
|
- Do not modify MeshCentral service configuration or enable debug logging without Rob's explicit request/approval.
|
||||||
|
- Do not print, copy, or log the credential contents.
|
||||||
|
- Stop immediately on unexpected protocol messages, TLS issues, authorization ambiguity, target ambiguity, sensitive output, or schema/action mismatch.
|
||||||
|
|
||||||
|
## Resume procedure
|
||||||
|
|
||||||
|
When Rob asks to resume:
|
||||||
|
|
||||||
|
1. Confirm the progress cron should be re-enabled; it is currently disabled.
|
||||||
|
2. Read this file, `RESUME-HANDOFF.md`, `review/FINAL-HARDENING-REVIEW.md`, and `LIVE-TEST-PROCEDURE.md`.
|
||||||
|
3. Obtain the exact MeshCentral 1.2.5 `meshctrl.js` source from the deployed LXC or an exact version-pinned package/source reference without exposing secrets.
|
||||||
|
4. Write `PROTOCOL-COMPARISON.md` with observed differences and a decision.
|
||||||
|
5. Add/update mock protocol tests for the identified handshake/request sequence.
|
||||||
|
6. Run tests/build/lint.
|
||||||
|
7. Only if the local protocol fix passes, prepare a revised single-target read-only test.
|
||||||
|
8. Execute the authorized read-only live connection; do not expand the scope beyond server version, groups, inventory, and PVE3 metadata.
|
||||||
|
9. Do not expand the scope beyond server version, groups, inventory, and PVE3 metadata.
|
||||||
|
|
||||||
|
## Project status at pause
|
||||||
|
|
||||||
|
**Local code:** verification-passing
|
||||||
|
**Live compatibility:** failed initial read-only attempt; unresolved
|
||||||
|
**Diagnostics:** mock-only
|
||||||
|
**Remote commands/state changes:** not implemented and prohibited
|
||||||
|
**Cron:** disabled by Rob
|
||||||
|
**Subagents:** none active
|
||||||
|
**Next work item:** controlled read-only live compatibility test
|
||||||
|
**Required user input now:** none; resume only when Rob asks
|
||||||
+90
@@ -0,0 +1,90 @@
|
|||||||
|
# Project goals and scope
|
||||||
|
|
||||||
|
## Primary goal
|
||||||
|
|
||||||
|
Build a secure, documented, local MeshCentral ↔ OpenClaw bridge that lets Rob ask OpenClaw for MeshCentral-backed system inventory and diagnostics, with confirmation-gated remote actions.
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
|
||||||
|
### Goal 1 — Establish a reliable read-only foundation
|
||||||
|
|
||||||
|
- Identify the supported MeshCentral integration surface (API, server-side module, MCP adapter, or another maintained approach).
|
||||||
|
- Authenticate using a dedicated least-privilege integration identity.
|
||||||
|
- List device groups and managed devices.
|
||||||
|
- Retrieve online/offline state and safe metadata.
|
||||||
|
- Provide clear, structured results to OpenClaw.
|
||||||
|
- Add health checks, timeouts, logging, and failure handling.
|
||||||
|
|
||||||
|
**Success condition:** OpenClaw can answer questions such as “Which managed systems are offline?” and “Show the OS, uptime, and agent status for this host” without changing anything.
|
||||||
|
|
||||||
|
### Goal 2 — Add safe diagnostics
|
||||||
|
|
||||||
|
- Define an allowlisted set of diagnostic checks.
|
||||||
|
- Support targeted checks for disk space, services, processes, OS details, network state, and relevant logs.
|
||||||
|
- Restrict execution by device/group allowlist and command policy.
|
||||||
|
- Return command output with device, timestamp, exit status, and truncation metadata.
|
||||||
|
|
||||||
|
**Success condition:** Rob can request a diagnostic investigation on one selected system and receive reproducible, auditable results.
|
||||||
|
|
||||||
|
### Goal 3 — Add confirmation-gated remediation
|
||||||
|
|
||||||
|
- Separate read-only, reversible, and destructive capabilities.
|
||||||
|
- Require explicit confirmation immediately before every state-changing action.
|
||||||
|
- Start with narrowly scoped reversible actions such as restarting an approved service.
|
||||||
|
- Keep reboot, shutdown, file deletion, software removal, security-control changes, and fleet-wide actions disabled by default.
|
||||||
|
|
||||||
|
**Success condition:** A requested change cannot occur from an ambiguous instruction, and every change is logged with target, action, requester, confirmation, result, and timestamp.
|
||||||
|
|
||||||
|
### Goal 4 — Make the integration operable and maintainable
|
||||||
|
|
||||||
|
- Document deployment, upgrades, rollback, secret handling, and incident response.
|
||||||
|
- Add automated tests and a non-production test target.
|
||||||
|
- Define backup and recovery expectations for bridge configuration.
|
||||||
|
- Record architectural decisions and known limitations.
|
||||||
|
|
||||||
|
**Success condition:** The bridge can be upgraded or removed without losing MeshCentral availability or creating unmanaged access.
|
||||||
|
|
||||||
|
## Scope boundaries
|
||||||
|
|
||||||
|
### In scope
|
||||||
|
|
||||||
|
- MeshCentral running in Rob’s Proxmox cluster
|
||||||
|
- A bridge deployed inside the trusted homelab network
|
||||||
|
- OpenClaw tool/MCP integration
|
||||||
|
- Device inventory, status, diagnostics, and selected confirmed actions
|
||||||
|
- Documentation, testing, auditability, and rollback
|
||||||
|
|
||||||
|
### Out of scope initially
|
||||||
|
|
||||||
|
- Publicly exposing the bridge
|
||||||
|
- Unrestricted arbitrary shell access
|
||||||
|
- Autonomous remediation or scheduled fleet changes
|
||||||
|
- Production Proxmox administration through MeshCentral
|
||||||
|
- Credential rotation or security-policy changes
|
||||||
|
- Integrating every possible MeshCentral feature before the read-only path is proven
|
||||||
|
|
||||||
|
## Proposed delivery phases
|
||||||
|
|
||||||
|
1. **Discovery:** confirm MeshCentral version, deployment topology, authentication options, API capabilities, and safe test devices.
|
||||||
|
2. **Design:** choose bridge protocol and deployment location; define trust boundaries and tool contracts.
|
||||||
|
3. **Read-only MVP:** inventory and status tools, structured responses, logging, tests.
|
||||||
|
4. **Diagnostics:** allowlisted checks against a non-production device first.
|
||||||
|
5. **Controlled actions:** confirmation gates and narrowly scoped reversible actions.
|
||||||
|
6. **Hardening:** failure testing, audit review, upgrade/rollback documentation, and operational handoff.
|
||||||
|
|
||||||
|
Each phase has a documented entry criterion, deliverables, verification, and exit criterion. No phase should silently expand into the next one.
|
||||||
|
|
||||||
|
## Multi-agent workflow
|
||||||
|
|
||||||
|
1. Clawdia maintains the task list and assigns non-overlapping work.
|
||||||
|
2. Research and implementation may proceed in parallel only where implementation is based on explicit assumptions or mocks.
|
||||||
|
3. Implementation agents write code and local tests, but do not deploy or connect to live infrastructure.
|
||||||
|
4. Review/test agents work from the resulting files and challenge assumptions independently.
|
||||||
|
5. Clawdia reconciles findings, updates decisions and task status, and identifies blockers.
|
||||||
|
6. Rob is asked only for choices that require local facts, credentials, topology decisions, or approval for external/state-changing work.
|
||||||
|
|
||||||
|
### First execution wave
|
||||||
|
|
||||||
|
- Research the available MeshCentral integration/API options and existing maintained adapters.
|
||||||
|
- Build a local, mock-backed read-only bridge scaffold with typed contracts and tests; do not assume live MeshCentral connectivity yet.
|
||||||
|
- After those outputs land, run an independent review/test pass before selecting the live-integration path.
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
# MeshCentral 1.2.5 protocol comparison
|
||||||
|
|
||||||
|
**Date:** 2026-08-26
|
||||||
|
**Reference:** deployed-version-pinned `meshctrl.js` source at commit
|
||||||
|
`b09b1d60328de8e2d2f7387561ed51c64011c82a`.
|
||||||
|
|
||||||
|
## Findings
|
||||||
|
|
||||||
|
| Area | Official MeshCtrl 1.2.5 | Bridge before this change | Decision |
|
||||||
|
|---|---|---|---|
|
||||||
|
| Password authentication | `base64(username),base64(password)` comma-separated header; optional third comma-separated base64 token | Base64 of `username:password[:totp]` | Correct bridge to official wire format |
|
||||||
|
| Request correlation | `responseid: "meshctrl"` | Numeric `id` | Use unique `responseid` values and match echoed `responseid` |
|
||||||
|
| Server-version response | `action: "serverversion"`, `responseid`, `result`, `tags` | Expected optional `ver` and numeric `id` | Accept protocol envelope and preserve response fields |
|
||||||
|
| First application message | No special handshake message; request is sent after `open` | Request sent after `open` | No extra handshake required |
|
||||||
|
| TLS | Official client disables certificate verification | Bridge requires verification | Keep bridge's safer behavior; do not copy upstream TLS weakness |
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
This comparison covers only the read-only control-channel operations used by the
|
||||||
|
MVP. Remote commands, diagnostics, events, power operations, file transfer, and
|
||||||
|
administrative actions remain out of scope.
|
||||||
|
|
||||||
|
## Compatibility consequence
|
||||||
|
|
||||||
|
The previous implementation could complete the WebSocket upgrade but was not
|
||||||
|
wire-compatible with MeshCentral's request/response correlation format. The
|
||||||
|
authentication-header and response-correlation corrections are now covered by
|
||||||
|
the local protocol tests before any further live read-only attempt.
|
||||||
@@ -0,0 +1,42 @@
|
|||||||
|
# MeshCentral ↔ OpenClaw Integration
|
||||||
|
|
||||||
|
Project to design, build, and safely operate a local integration between Rob's MeshCentral deployment and OpenClaw.
|
||||||
|
|
||||||
|
## Vision
|
||||||
|
|
||||||
|
Allow OpenClaw to use MeshCentral as a controlled remote-management interface for homelab systems—starting with read-only inventory and diagnostics, then adding explicitly confirmed remediation actions.
|
||||||
|
|
||||||
|
## Project status
|
||||||
|
|
||||||
|
**Stage:** Discovery / design
|
||||||
|
**Created:** 2026-08-24
|
||||||
|
**Owner:** Rob
|
||||||
|
**Project manager:** Clawdia
|
||||||
|
**Working name:** MeshCentral OpenClaw Bridge
|
||||||
|
|
||||||
|
## Execution model
|
||||||
|
|
||||||
|
This project will be run as a supervised multi-agent build:
|
||||||
|
|
||||||
|
- **Research agent:** investigates MeshCentral's supported integration surfaces, existing maintained projects, version compatibility, and security implications.
|
||||||
|
- **Implementation agent:** creates the bridge code, tests, schemas, and deployment scaffolding in the project workspace.
|
||||||
|
- **Review/test agent:** independently reviews the implementation, runs available tests, checks security controls, and reports defects or missing coverage.
|
||||||
|
- **Clawdia / project manager:** decomposes work, assigns isolated scopes, reviews results, tracks progress, prevents stalled work from being silently accepted, and brings only decisions requiring Rob's input back to Rob.
|
||||||
|
|
||||||
|
Agents must not modify infrastructure, MeshCentral, Proxmox, endpoints, or external systems during development unless Rob explicitly authorizes that action. The initial work is research, local code, documentation, mocks, and tests only.
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
- [Project goals and scope](PROJECT.md)
|
||||||
|
- [Security and safety requirements](SECURITY.md)
|
||||||
|
- [Architecture decisions](DECISIONS.md)
|
||||||
|
- [Initial task list](TODO.md)
|
||||||
|
|
||||||
|
## Non-goals for the initial release
|
||||||
|
|
||||||
|
- Unrestricted arbitrary command execution
|
||||||
|
- Autonomous fleet-wide changes
|
||||||
|
- Public exposure of MeshCentral or the bridge
|
||||||
|
- Replacing MeshCentral's normal administration interface
|
||||||
|
- Touching Proxmox production infrastructure as part of this project
|
||||||
|
**Gitea repository:** https://gitea.ledrew.me/ledadmin/meshcentral-openclaw-bridge
|
||||||
@@ -0,0 +1,89 @@
|
|||||||
|
# MeshCentral ↔ OpenClaw Bridge — Resume Handoff
|
||||||
|
|
||||||
|
**Checkpoint:** 2026-08-25 09:18 EDT
|
||||||
|
**Owner:** Rob / Clawdia
|
||||||
|
**Project state:** Active. Rob authorized read-only MeshCentral access for this project on 2026-08-26. A corrected live test is pending.
|
||||||
|
|
||||||
|
## What was completed in the resumed work session
|
||||||
|
|
||||||
|
1. Repaired the TypeScript regression in `implementation/src/adapter.ts` where a literal `\\n` had been inserted into source line 316.
|
||||||
|
2. Removed two unused-variable lint failures exposed after the repair.
|
||||||
|
3. Added protocol validation to `implementation/src/meshctrl-client.ts`:
|
||||||
|
- bounded response size using `MAX_RESPONSE_SIZE`
|
||||||
|
- JSON/protocol envelope validation
|
||||||
|
- action-specific response schema validation using Zod
|
||||||
|
- request/response action matching
|
||||||
|
- generic MeshCentral request errors instead of exposing server error text
|
||||||
|
4. Hardened credential handling:
|
||||||
|
- credentials are validated before encoding
|
||||||
|
- malformed credentials are rejected
|
||||||
|
- credential metadata is redacted
|
||||||
|
- no password/token is written to project files or logs
|
||||||
|
5. Corrected real-adapter device and group allowlist filtering in `implementation/src/adapter.ts`.
|
||||||
|
6. Added `implementation/src/__tests__/meshctrl-client.test.ts` covering:
|
||||||
|
- valid and malformed credentials
|
||||||
|
- redacted credential metadata
|
||||||
|
- malformed and oversized responses
|
||||||
|
- response action mismatches
|
||||||
|
- invalid node response data
|
||||||
|
7. Exported `validateResponseForAction` from `implementation/src/index.ts`.
|
||||||
|
8. Updated `implementation/README.md` to describe the real adapter accurately and clearly mark it as not live-approved; diagnostics remain mock-only.
|
||||||
|
|
||||||
|
## Verification at checkpoint
|
||||||
|
|
||||||
|
Run from `implementation/`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm test -- --runInBand
|
||||||
|
npm run build
|
||||||
|
npm run lint
|
||||||
|
```
|
||||||
|
|
||||||
|
Last successful result:
|
||||||
|
|
||||||
|
- 9 test suites passed
|
||||||
|
- 56 tests passed
|
||||||
|
- TypeScript build passed
|
||||||
|
- ESLint passed
|
||||||
|
- `tsc --noEmit` passed
|
||||||
|
|
||||||
|
## Current phase
|
||||||
|
|
||||||
|
Post-hardening protocol compatibility validation. The implementation is authorized for the narrow read-only live test described in `LIVE-TEST-PROCEDURE.md`.
|
||||||
|
|
||||||
|
## Remaining work, in order
|
||||||
|
|
||||||
|
1. Add bounded request concurrency/rate limiting to the MeshCtrl client.
|
||||||
|
2. Add structured audit logging for authentication, requests, targets, results, timestamps, and failures; never log passwords, TOTP tokens, session tokens, or raw sensitive output.
|
||||||
|
3. Add negative/security tests for retries, timeouts, connection failures, allowlist enforcement, and logging redaction.
|
||||||
|
4. Finish deployment and rollback documentation, including the live-test checklist.
|
||||||
|
5. Run an independent security review against the updated source and address findings.
|
||||||
|
6. Execute the authorized read-only live-test procedure; do not expand its scope.
|
||||||
|
7. Keep diagnostics mock-only; do not add remote commands or state-changing actions until separately designed and reviewed.
|
||||||
|
|
||||||
|
## Live-test facts already documented
|
||||||
|
|
||||||
|
See `DEPLOYMENT.md`. It records the reported MeshCentral host/version, the dedicated integration account name, the intended PVE3 test target, secret-handling rules, prerequisites, and the explicit approval checkpoint. The password is intentionally not stored in this project.
|
||||||
|
|
||||||
|
## Safety constraints
|
||||||
|
|
||||||
|
- Do not connect to MeshCentral without Rob's explicit go-ahead in the same step.
|
||||||
|
- Do not use or store the integration password in source, prompts, command lines, logs, or this handoff.
|
||||||
|
- Do not execute remote commands or state-changing actions.
|
||||||
|
- Do not modify infrastructure.
|
||||||
|
- PVE1/PVE2 production cluster remains off-limits for testing.
|
||||||
|
|
||||||
|
## Scheduler state
|
||||||
|
|
||||||
|
The `meshcentral-project-progress` cron job is disabled/paused at Rob's request. Re-enable it only when Rob asks.
|
||||||
|
|
||||||
|
## Suggested resume procedure
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /home/ledadmin/projects/meshcentral-openclaw-bridge/implementation
|
||||||
|
npm test -- --runInBand
|
||||||
|
npm run build
|
||||||
|
npm run lint
|
||||||
|
```
|
||||||
|
|
||||||
|
Then inspect this file, `TODO.md`, `SECURITY.md`, `DEPLOYMENT.md`, and `review/LIVE-ADAPTER-REVIEW.md` before continuing with the next remaining item.
|
||||||
+46
@@ -0,0 +1,46 @@
|
|||||||
|
# Security and safety requirements
|
||||||
|
|
||||||
|
## Baseline
|
||||||
|
|
||||||
|
This bridge is a remote-management control plane. Treat its credentials and command path as highly sensitive.
|
||||||
|
|
||||||
|
## Required controls
|
||||||
|
|
||||||
|
- Use a dedicated MeshCentral account, never Rob’s primary administrator account.
|
||||||
|
- Grant the minimum MeshCentral permissions needed for the current phase.
|
||||||
|
- Keep the bridge on the trusted LAN or an isolated management network.
|
||||||
|
- Do not expose MeshCentral, the bridge, or an MCP endpoint directly to the public internet.
|
||||||
|
- Store secrets in a protected runtime secret store or environment file with restrictive permissions; never commit secrets.
|
||||||
|
- Use TLS for connections where supported and validate certificates appropriately.
|
||||||
|
- Authenticate and authorize every bridge request.
|
||||||
|
- Restrict targets using explicit device/group allowlists.
|
||||||
|
- Apply command allowlists or typed operations rather than accepting unrestricted shell text by default.
|
||||||
|
- Log authentication events, requests, target, operation, confirmation, result, and timestamp without logging secrets.
|
||||||
|
- Set timeouts, output limits, concurrency limits, and rate limits.
|
||||||
|
- Fail closed when the bridge, MeshCentral, or authorization state is uncertain.
|
||||||
|
- Provide a kill switch and documented rollback procedure.
|
||||||
|
|
||||||
|
## Action classes
|
||||||
|
|
||||||
|
| Class | Examples | Default policy |
|
||||||
|
|---|---|---|
|
||||||
|
| Read-only | Inventory, status, uptime, disk usage, service state | Allowed after authentication |
|
||||||
|
| Diagnostic execution | Approved health checks, log collection, connectivity tests | Targeted; explicit request; logged |
|
||||||
|
| Reversible change | Restart an approved service, create a diagnostic bundle | Immediate explicit confirmation |
|
||||||
|
| Disruptive change | Reboot, shutdown, stop service, change network settings | Explicit confirmation with impact shown |
|
||||||
|
| Destructive/high-risk | Delete files, uninstall software, disable security, arbitrary scripts | Disabled initially; separate approval/design required |
|
||||||
|
|
||||||
|
## OpenClaw-specific safety rule
|
||||||
|
|
||||||
|
Availability of a MeshCentral capability is not permission to use it. A state-changing operation requires Rob’s clear instruction and a confirmation immediately before execution. Ambiguous requests are clarification points, not authorization.
|
||||||
|
|
||||||
|
## Threat model to review
|
||||||
|
|
||||||
|
- Compromise of the bridge host or MeshCentral LXC
|
||||||
|
- Theft or misuse of the integration credential
|
||||||
|
- Prompt injection from endpoint output or device names
|
||||||
|
- Accidental targeting of the wrong device or group
|
||||||
|
- Command output containing secrets or personal data
|
||||||
|
- Replay or duplicate execution of an action
|
||||||
|
- MeshCentral/API version changes
|
||||||
|
- Network partition or partial execution across multiple targets
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
# Session checkpoint — 2026-08-26
|
||||||
|
|
||||||
|
## Requested action
|
||||||
|
Rob requested that the current project state be written into the project folder and that the project cron jobs be stopped for today.
|
||||||
|
|
||||||
|
## Final state at pause
|
||||||
|
- Project: `meshcentral-openclaw-bridge`
|
||||||
|
- Status: **BLOCKED / PAUSED FOR TODAY**
|
||||||
|
- Live-test attempts/failures: **3 consecutive failures**
|
||||||
|
- Failure stage: `serverversion` (`protocol-or-connection`)
|
||||||
|
- Live testing: **STOPPED by configured failure-limit rule**
|
||||||
|
- Worker: no active worker process or lock at checkpoint
|
||||||
|
- Progress cron: being disabled for today; configuration is preserved
|
||||||
|
|
||||||
|
## Work completed this session
|
||||||
|
- Reviewed project folder, handoff, status, TODO, deployment, live-test, security, research, implementation, and review documents.
|
||||||
|
- Confirmed local implementation quality gate before the live attempts:
|
||||||
|
- Initial baseline: 90 tests passed, build passed, lint passed.
|
||||||
|
- After secure live-test runner: 91 tests passed, build passed, lint passed.
|
||||||
|
- After final runner/diagnostic changes: 12 suites, 91 tests passed, build passed, lint passed with no warnings.
|
||||||
|
- Corrected MeshCentral 1.2.5 protocol assumptions:
|
||||||
|
- `x-meshauth` uses comma-separated Base64 fields for username/password and optional TOTP.
|
||||||
|
- Requests/responses correlate using `responseid`, not the bridge's former numeric `id` field.
|
||||||
|
- Official server-version responses use fields including `result` and `tags`.
|
||||||
|
- Added `PROTOCOL-COMPARISON.md`.
|
||||||
|
- Added fixed-scope `implementation/src/live-readonly-test.ts` and `npm run live-test`.
|
||||||
|
- Runner reads the protected credential file internally and does not accept credential, operation, or target CLI arguments.
|
||||||
|
- Runner scope is fixed to server version, `Servers` group, `nodes`, and PVE3 `deviceinfo`.
|
||||||
|
- Added runner safety test and sanitized stage-level failure reporting.
|
||||||
|
- Reconciled stale authorization/status wording in project documentation.
|
||||||
|
- Added `PROJECT-PROGRESS.json`, `worker/run-worker.js`, and `worker/worker.log` as an attempted durable-worker/watchdog arrangement.
|
||||||
|
|
||||||
|
## Live-test result
|
||||||
|
- TLS and WebSocket setup reached the server successfully.
|
||||||
|
- The fixed-scope probe failed at the first `serverversion` request stage on three consecutive attempts.
|
||||||
|
- No groups, inventory, PVE3 metadata, commands, diagnostics, file transfer, power operations, administrative actions, or state changes completed.
|
||||||
|
- No credentials, authentication headers, tokens, or raw server error text were written to project files or logs.
|
||||||
|
|
||||||
|
## Worker/watchdog findings
|
||||||
|
- One-shot subagent workers exited before completing their intended checkpoints.
|
||||||
|
- A detached Node worker was then attempted; it did execute verification and live probes, but its log remained empty because child output was buffered and checkpoint logging was incomplete.
|
||||||
|
- `PROJECT-PROGRESS.json` is the authoritative persisted state; it records the third live failure and the stop rule.
|
||||||
|
- The watchdog cron was converted to a 15-minute watchdog but had intermittent setup timeouts. It is being paused for today per Rob's request.
|
||||||
|
|
||||||
|
## Current blocker and next action
|
||||||
|
**Blocker:** MeshCentral control-channel compatibility/authentication remains unresolved at `serverversion` after WebSocket connection setup.
|
||||||
|
|
||||||
|
Before resuming:
|
||||||
|
1. Inspect the exact sanitized close/error behavior and compare against deployed MeshCentral 1.2.5 server behavior.
|
||||||
|
2. Repair or replace the worker orchestration/logging so active work is observable and state updates are reliable.
|
||||||
|
3. Do not reset the live-failure count or retry live testing until the protocol hypothesis changes and the retry policy is explicitly reviewed.
|
||||||
|
4. Preserve read-only scope: `serverversion`, `meshes`, `nodes`, `deviceinfo`; PVE3 only.
|
||||||
|
|
||||||
|
## Safety boundaries
|
||||||
|
- MeshCentral access: read-only only.
|
||||||
|
- Approved target: PVE3 only.
|
||||||
|
- Prohibited: commands, diagnostics, power operations, file transfer, administration, state changes, PVE1, and PVE2.
|
||||||
|
- Credential file remains outside the project at the protected path and must not be copied, logged, or exposed.
|
||||||
|
|
||||||
|
## Resume note
|
||||||
|
The project may be resumed by explicitly reviewing this checkpoint and `PROJECT-PROGRESS.json`. The progress cron is disabled, not deleted, and can be re-enabled later without recreating it.
|
||||||
@@ -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
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"parser": "@typescript-eslint/parser",
|
||||||
|
"plugins": ["@typescript-eslint"],
|
||||||
|
"extends": [
|
||||||
|
"eslint:recommended",
|
||||||
|
"plugin:@typescript-eslint/recommended"
|
||||||
|
],
|
||||||
|
"rules": {
|
||||||
|
"no-console": "warn",
|
||||||
|
"@typescript-eslint/no-explicit-any": "error",
|
||||||
|
"@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
|
||||||
|
"@typescript-eslint/strict-boolean-expressions": "off",
|
||||||
|
"@typescript-eslint/no-unused-expressions": "warn"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,202 @@
|
|||||||
|
# MeshCentral ↔ OpenClaw Bridge - Implementation
|
||||||
|
|
||||||
|
Read-only bridge for device inventory and diagnostics between MeshCentral and OpenClaw.
|
||||||
|
|
||||||
|
> **⚠️ READ-ONLY LIVE TESTING** - The real MeshCentral control-channel adapter is authorized for the project's narrowly scoped read-only compatibility test. Diagnostics remain mock-only. Commands, state changes, and production-cluster access are prohibited.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This implementation provides:
|
||||||
|
|
||||||
|
- **Typed contracts** - Zod schemas for all data structures
|
||||||
|
- **Adapter pattern** - Clean boundary between bridge and MeshCentral client
|
||||||
|
- **Mock-backed** - Works offline with sample data for development/testing
|
||||||
|
- **Structured errors** - Consistent error handling with codes and metadata
|
||||||
|
- **Timeouts/output limits** - Configurable safeguards for operations
|
||||||
|
|
||||||
|
## Project Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
implementation/
|
||||||
|
├── src/
|
||||||
|
│ ├── index.ts # Main entry point
|
||||||
|
│ ├── contracts.ts # Typed schemas and interfaces
|
||||||
|
│ ├── adapter.ts # Adapter factory and base interface
|
||||||
|
│ ├── mock-adapter.ts # Mock implementation for development
|
||||||
|
│ └── __tests__/ # Test suite
|
||||||
|
├── package.json # Node.js dependencies
|
||||||
|
├── tsconfig.json # TypeScript configuration
|
||||||
|
├── jest.config.js # Jest test configuration
|
||||||
|
├── example-config.json # Development/testing config
|
||||||
|
└── example-config-real.json # Real MeshCentral integration config (needs credentials)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### Install Dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd implementation
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run Tests (Mock Data Only)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# All tests - uses mock data, no MeshCentral connection required
|
||||||
|
npm test
|
||||||
|
|
||||||
|
# Watch mode (development)
|
||||||
|
npm run test:watch
|
||||||
|
|
||||||
|
# With coverage
|
||||||
|
npm test -- --coverage
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
### Lint
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run lint
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage Example
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { createMeshCentralAdapter, DeviceStatus } from './src/index';
|
||||||
|
|
||||||
|
async function main() {
|
||||||
|
// Create adapter with configuration
|
||||||
|
const adapter = createMeshCentralAdapter({
|
||||||
|
meshCentralUrl: 'http://10.10.10.60:8080',
|
||||||
|
adapterType: 'mock', // Safe local mode; real mode is read-only and PVE3-scoped
|
||||||
|
timeoutMs: 10_000,
|
||||||
|
maxOutputLength: 65_536,
|
||||||
|
});
|
||||||
|
|
||||||
|
// List all devices (uses mock data)
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
console.log(`Found ${devices.length} devices`);
|
||||||
|
|
||||||
|
// Filter by group
|
||||||
|
const onlineDevices = await adapter.listDevices({ groupId: 'grp-servers' });
|
||||||
|
console.log(`Online servers: ${onlineDevices.length}`);
|
||||||
|
|
||||||
|
// Get device details
|
||||||
|
const device = await adapter.getDevice('dev-001');
|
||||||
|
console.log(`Device: ${device.name} (${device.status})`);
|
||||||
|
|
||||||
|
// Run diagnostics (mock data only - no real system commands executed)
|
||||||
|
const diskSpace = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: 'diskSpace',
|
||||||
|
});
|
||||||
|
console.log(diskSpace.output);
|
||||||
|
|
||||||
|
// Health check (mock always returns healthy)
|
||||||
|
const healthy = await adapter.healthCheck();
|
||||||
|
console.log(`Bridge healthy: ${healthy}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
main().catch(console.error);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
| Option | Type | Default | Description |
|
||||||
|
|--------|------|---------|-------------|
|
||||||
|
| `meshCentralUrl` | string | `'http://localhost:8080'` | MeshCentral server URL (unused in mock mode) |
|
||||||
|
| `adapterType` | `'real' \| 'mock'` | `'mock'` | Use `mock` for local tests; `real` requires credentials and a reviewed live-test environment |
|
||||||
|
| `timeoutMs` | number | `10_000` | Request timeout in milliseconds |
|
||||||
|
| `maxOutputLength` | number | `65_536` | Maximum output bytes for diagnostics (truncates if exceeded) |
|
||||||
|
|
||||||
|
> **Note:** The real adapter uses MeshCentral's `/control.ashx` WebSocket protocol for read-only inventory/status calls. Diagnostics still return mock data; no remote commands or state-changing operations are implemented.
|
||||||
|
|
||||||
|
## Supported Diagnostic Checks
|
||||||
|
|
||||||
|
> **⚠️ MOCK DATA ONLY** - All diagnostic outputs are simulated static strings. No real system commands are executed.
|
||||||
|
|
||||||
|
- `diskSpace` - Simulated filesystem usage statistics
|
||||||
|
- `services` - Simulated system service status
|
||||||
|
- `processes` - Simulated running process list
|
||||||
|
- `osDetails` - Simulated operating system version info
|
||||||
|
- `networkState` - Simulated network interface configuration
|
||||||
|
- `uptime` - Simulated system uptime and load average
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
All errors include a code from the `ErrorCodes` enum:
|
||||||
|
|
||||||
|
| Code | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `ADAPTER_NOT_FOUND` | Adapter method not implemented |
|
||||||
|
| `CONFIGURATION_INVALID` | Invalid configuration provided |
|
||||||
|
| `TIMEOUT_EXCEEDED` | Request timed out |
|
||||||
|
| `OUTPUT_LIMIT_EXCEEDED` | Output exceeded maxOutputLength (truncated) |
|
||||||
|
| `AUTHENTICATION_FAILED` | Authentication error (**not implemented**) |
|
||||||
|
| `CONNECTION_FAILED` | Network connection failed (**not implemented**) |
|
||||||
|
| `RESOURCE_NOT_FOUND` | Device or group not found |
|
||||||
|
| `MESHCENTRAL_ERROR` | Generic MeshCentral API error (**not implemented**) |
|
||||||
|
|
||||||
|
## Adapter Status
|
||||||
|
|
||||||
|
### Mock Adapter ✅
|
||||||
|
- Device listing and filtering by group
|
||||||
|
- Device details retrieval
|
||||||
|
- Group listing and lookup
|
||||||
|
- Diagnostic execution with simulated output
|
||||||
|
- Health check
|
||||||
|
|
||||||
|
### Real Adapter ⚠️ (**Read-only scope only**)
|
||||||
|
|
||||||
|
> The real adapter is implemented locally and may be used only for the documented read-only compatibility test. It must remain limited to the approved MeshCentral account and PVE3 target.
|
||||||
|
|
||||||
|
- **MeshCentral control-channel integration** - Implemented locally via `/control.ashx`
|
||||||
|
- **Device/group inventory and status** - Implemented locally
|
||||||
|
- **Response size and schema validation** - Implemented and unit-tested
|
||||||
|
- **Real-time status updates** - Not implemented
|
||||||
|
- **Actual command execution** - Not implemented (diagnostics use mock data)
|
||||||
|
|
||||||
|
## Testing Strategy
|
||||||
|
|
||||||
|
Tests are organized into:
|
||||||
|
|
||||||
|
1. **contract.test.ts** - Schema validation and type safety
|
||||||
|
2. **mock-adapter.test.ts** - Mock adapter behavior and edge cases
|
||||||
|
3. **integration.test.ts** - Full workflow validation
|
||||||
|
4. **adapter-factory.test.ts** - Adapter creation and configuration
|
||||||
|
|
||||||
|
## Future Implementation Notes
|
||||||
|
|
||||||
|
### Real MeshCentral Integration
|
||||||
|
|
||||||
|
The adapter uses the MeshCentral control WebSocket rather than the illustrative HTTP endpoints below. The protocol implementation is still subject to version-specific live verification:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Historical/illustrative endpoints; not used by the current adapter
|
||||||
|
const ENDPOINTS = {
|
||||||
|
devices: '/api/devices',
|
||||||
|
device: (id: string) => `/api/device/${id}`,
|
||||||
|
groups: '/api/groups',
|
||||||
|
diagnostics: (deviceId: string) => `/api/device/${deviceId}/diagnostics`,
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Authentication will use MeshCentral's token-based auth.
|
||||||
|
|
||||||
|
> **⚠️ SECURITY REQUIRED** - Do not enable TLS validation bypass (`rejectUnauthorized: false`). Certificate verification must be enabled for production use.
|
||||||
|
|
||||||
|
### Adding New Diagnostic Checks
|
||||||
|
|
||||||
|
1. Add check type to `DiagnosticCheckType` enum in `contracts.ts`
|
||||||
|
2. Implement output in `DIAGNOSTIC_OUTPUTS` map in `mock-adapter.ts`
|
||||||
|
3. Add test coverage in `integration.test.ts`
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
@@ -0,0 +1,6 @@
|
|||||||
|
{
|
||||||
|
"meshCentralUrl": "http://10.10.10.60:8080",
|
||||||
|
"adapterType": "real",
|
||||||
|
"timeoutMs": 30000,
|
||||||
|
"maxOutputLength": 65536
|
||||||
|
}
|
||||||
@@ -0,0 +1,6 @@
|
|||||||
|
{
|
||||||
|
"meshCentralUrl": "http://192.168.1.10:8080",
|
||||||
|
"adapterType": "mock",
|
||||||
|
"timeoutMs": 10000,
|
||||||
|
"maxOutputLength": 65536
|
||||||
|
}
|
||||||
@@ -0,0 +1,14 @@
|
|||||||
|
/**
|
||||||
|
* Jest configuration for bridge tests.
|
||||||
|
*/
|
||||||
|
|
||||||
|
/** @type {import('jest').Config} */
|
||||||
|
module.exports = {
|
||||||
|
testEnvironment: 'node',
|
||||||
|
transform: {
|
||||||
|
'^.+\\.ts$': ['ts-jest', { useESM: false }],
|
||||||
|
},
|
||||||
|
testMatch: ['**/__tests__/**/*.test.ts'],
|
||||||
|
collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
|
||||||
|
moduleFileExtensions: ['ts', 'js'],
|
||||||
|
};
|
||||||
Generated
+5570
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,38 @@
|
|||||||
|
{
|
||||||
|
"name": "meshcentral-openclaw-bridge",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"description": "MeshCentral ↔ OpenClaw Bridge - Read-only inventory and diagnostics",
|
||||||
|
"main": "dist/index.js",
|
||||||
|
"types": "dist/index.d.ts",
|
||||||
|
"scripts": {
|
||||||
|
"build": "tsc",
|
||||||
|
"test": "jest",
|
||||||
|
"test:watch": "jest --watch",
|
||||||
|
"lint": "eslint 'src/**/*.ts' && tsc --noEmit",
|
||||||
|
"live-test": "node dist/live-readonly-test.js"
|
||||||
|
},
|
||||||
|
"keywords": [
|
||||||
|
"meshcentral",
|
||||||
|
"openclaw",
|
||||||
|
"bridge"
|
||||||
|
],
|
||||||
|
"author": "",
|
||||||
|
"license": "MIT",
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/jest": "^29.5.14",
|
||||||
|
"@types/node": "^22.13.5",
|
||||||
|
"@typescript-eslint/eslint-plugin": "^8.24.0",
|
||||||
|
"@typescript-eslint/parser": "^8.24.0",
|
||||||
|
"eslint": "^8.57.1",
|
||||||
|
"jest": "^29.7.0",
|
||||||
|
"jest-extended": "^4.0.2",
|
||||||
|
"ts-jest": "^29.3.0",
|
||||||
|
"typescript": "^5.7.3"
|
||||||
|
},
|
||||||
|
"dependencies": {
|
||||||
|
"@types/ws": "^8.18.1",
|
||||||
|
"axios": "^1.8.1",
|
||||||
|
"ws": "^8.21.3",
|
||||||
|
"zod": "^3.24.2"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,39 @@
|
|||||||
|
/**
|
||||||
|
* Tests for the adapter factory function.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { createMeshCentralAdapter } from '../adapter';
|
||||||
|
import { BridgeError } from '../contracts';
|
||||||
|
|
||||||
|
describe('createMeshCentralAdapter', () => {
|
||||||
|
it('should return mock adapter by default', () => {
|
||||||
|
const adapter = createMeshCentralAdapter();
|
||||||
|
expect(adapter.name).toBe('mock');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return mock adapter when adapterType is mock', () => {
|
||||||
|
const adapter = createMeshCentralAdapter({ adapterType: 'mock' });
|
||||||
|
expect(adapter.name).toBe('mock');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw for real adapter without credentials', async () => {
|
||||||
|
// Real adapter requires credentials
|
||||||
|
expect(() =>
|
||||||
|
createMeshCentralAdapter({ adapterType: 'real', meshCentralUrl: 'http://test:8080' }),
|
||||||
|
).toThrow(BridgeError);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should accept custom configuration', () => {
|
||||||
|
const config = {
|
||||||
|
meshCentralUrl: 'http://custom-url:8080',
|
||||||
|
timeoutMs: 5_000,
|
||||||
|
maxOutputLength: 32_768,
|
||||||
|
};
|
||||||
|
|
||||||
|
const adapter = createMeshCentralAdapter(config);
|
||||||
|
expect(adapter.name).toBe('mock');
|
||||||
|
|
||||||
|
// Verify mock adapter receives config (would be used by real adapter)
|
||||||
|
expect(adapter).toBeDefined();
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,238 @@
|
|||||||
|
/**
|
||||||
|
* Unit tests for audit logging and secret redaction.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import {
|
||||||
|
createAuditEntry,
|
||||||
|
sanitizeForLogging,
|
||||||
|
redactSecrets,
|
||||||
|
isSecurityCritical,
|
||||||
|
AuditAction,
|
||||||
|
AuditStatus,
|
||||||
|
AuditLogEntry,
|
||||||
|
} from '../audit';
|
||||||
|
|
||||||
|
describe('Audit Logging - Redaction', () => {
|
||||||
|
describe('redactSecrets', () => {
|
||||||
|
it('should redact base64-encoded credentials', () => {
|
||||||
|
const input = 'Authorization: Basic dXNlcjpwYXNzd29yZA==';
|
||||||
|
const result = redactSecrets(input);
|
||||||
|
expect(result).not.toContain('dXNlcjpwYXNzd29yZA==');
|
||||||
|
expect(result).toContain('[REDACTED_BASE64]');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should redact hex-encoded secrets', () => {
|
||||||
|
// Use a 32+ char hex string that doesn't look like base64
|
||||||
|
const input = 'secret: 1234567890abcdef1234567890abcdef';
|
||||||
|
const result = redactSecrets(input);
|
||||||
|
expect(result).not.toContain('1234567890abcdef1234567890abcdef');
|
||||||
|
expect(result).toContain('[REDACTED_HEX]');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should redact passwords in JSON objects', () => {
|
||||||
|
const input = { username: 'admin', password: 'secret123' };
|
||||||
|
const result = redactSecrets(input);
|
||||||
|
expect(result).not.toContain('secret123');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should redact sensitive header values', () => {
|
||||||
|
const input = { 'x-meshauth': 'dXNlcjpwYXNzd29yZA==' };
|
||||||
|
const result = redactSecrets(input);
|
||||||
|
expect(result).not.toContain('dXNlcjpwYXNzd29yZA==');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should preserve non-sensitive data', () => {
|
||||||
|
const input = { username: 'admin', url: 'http://example.com' };
|
||||||
|
const result = redactSecrets(input);
|
||||||
|
expect(result).toContain('admin');
|
||||||
|
expect(result).toContain('http://example.com');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('sanitizeForLogging', () => {
|
||||||
|
it('should redact known secret keys', () => {
|
||||||
|
const input = {
|
||||||
|
username: 'admin',
|
||||||
|
password: 'secret123',
|
||||||
|
token: 'abc123',
|
||||||
|
secret: 'hidden',
|
||||||
|
};
|
||||||
|
const result = sanitizeForLogging(input);
|
||||||
|
expect(result.password).toBe('[REDACTED]');
|
||||||
|
expect(result.token).toBe('[REDACTED]');
|
||||||
|
expect(result.secret).toBe('[REDACTED]');
|
||||||
|
expect(result.username).toBe('admin');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle nested objects', () => {
|
||||||
|
const input = {
|
||||||
|
credentials: {
|
||||||
|
username: 'admin',
|
||||||
|
password: 'secret123',
|
||||||
|
},
|
||||||
|
url: 'http://example.com',
|
||||||
|
};
|
||||||
|
const result = sanitizeForLogging(input);
|
||||||
|
expect((result as { credentials: { password: unknown } }).credentials.password).toBe('[REDACTED]');
|
||||||
|
expect(result.url).toBe('http://example.com');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle arrays', () => {
|
||||||
|
const input = [
|
||||||
|
{ username: 'admin1', password: 'secret1' },
|
||||||
|
{ username: 'admin2', password: 'secret2' },
|
||||||
|
];
|
||||||
|
const result = sanitizeForLogging(input);
|
||||||
|
expect((result as Array<{ password: unknown }>)[0].password).toBe('[REDACTED]');
|
||||||
|
expect((result as Array<{ password: unknown }>)[1].password).toBe('[REDACTED]');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return primitives unchanged', () => {
|
||||||
|
expect(sanitizeForLogging('string')).toBe('string');
|
||||||
|
expect(sanitizeForLogging(123)).toBe(123);
|
||||||
|
expect(sanitizeForLogging(true)).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Audit Logging - Entry Creation', () => {
|
||||||
|
it('should create a complete audit entry', () => {
|
||||||
|
const entry = createAuditEntry({
|
||||||
|
action: AuditAction.AUTH_ATTEMPT,
|
||||||
|
status: AuditStatus.SUCCESS,
|
||||||
|
actor: 'admin',
|
||||||
|
resource: 'device-001',
|
||||||
|
details: { reason: 'login', success: true },
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(entry.timestamp).toBeDefined();
|
||||||
|
expect(entry.action).toBe(AuditAction.AUTH_ATTEMPT);
|
||||||
|
expect(entry.status).toBe(AuditStatus.SUCCESS);
|
||||||
|
expect(entry.actor).toBe('admin');
|
||||||
|
expect(entry.resource).toBe('device-001');
|
||||||
|
expect(entry.details).toBeDefined();
|
||||||
|
expect(entry.details?.reason).toBe('login');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should redact secrets in details', () => {
|
||||||
|
const entry = createAuditEntry({
|
||||||
|
action: AuditAction.AUTH_ATTEMPT,
|
||||||
|
status: AuditStatus.SUCCESS,
|
||||||
|
actor: 'admin',
|
||||||
|
resource: 'device-001',
|
||||||
|
details: {
|
||||||
|
password: 'secret123',
|
||||||
|
username: 'admin',
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(entry.details?.password).toBe('[REDACTED]');
|
||||||
|
expect(entry.details?.username).toBe('admin');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should use defaults when fields are missing', () => {
|
||||||
|
const entry = createAuditEntry({
|
||||||
|
action: AuditAction.CONFIG_CHANGE,
|
||||||
|
status: AuditStatus.PENDING,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(entry.actor).toBe('unknown');
|
||||||
|
expect(entry.resource).toBe('unknown');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Audit Logging - Security Critical Actions', () => {
|
||||||
|
it('should identify security-critical actions', () => {
|
||||||
|
expect(isSecurityCritical(AuditAction.AUTH_ATTEMPT)).toBe(true);
|
||||||
|
expect(isSecurityCritical(AuditAction.CREDENTIAL_UPDATE)).toBe(true);
|
||||||
|
expect(isSecurityCritical(AuditAction.CONNECTION_ATTEMPT)).toBe(true);
|
||||||
|
expect(isSecurityCritical(AuditAction.CONFIG_CHANGE)).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should identify non-security-critical actions', () => {
|
||||||
|
expect(isSecurityCritical(AuditAction.DEVICE_LISTED)).toBe(false);
|
||||||
|
expect(isSecurityCritical(AuditAction.GROUP_LISTED)).toBe(false);
|
||||||
|
expect(isSecurityCritical(AuditAction.SERVICE_START)).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Audit Logging - Schema Validation', () => {
|
||||||
|
it('should validate a proper audit entry', () => {
|
||||||
|
const validEntry: AuditLogEntry = {
|
||||||
|
timestamp: new Date().toISOString(),
|
||||||
|
action: AuditAction.AUTH_ATTEMPT,
|
||||||
|
status: AuditStatus.SUCCESS,
|
||||||
|
actor: 'admin',
|
||||||
|
resource: 'device-001',
|
||||||
|
};
|
||||||
|
|
||||||
|
// Import isAuditLogEntry from types if available, or test manually
|
||||||
|
const isValid = validateEntry(validEntry);
|
||||||
|
expect(isValid).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should reject invalid entries', () => {
|
||||||
|
const validTimestamp = new Date().toISOString();
|
||||||
|
|
||||||
|
// Invalid timestamp
|
||||||
|
const invalidEntry1 = {
|
||||||
|
timestamp: 'invalid-date',
|
||||||
|
action: AuditAction.AUTH_ATTEMPT,
|
||||||
|
status: AuditStatus.SUCCESS,
|
||||||
|
};
|
||||||
|
|
||||||
|
const isValid1 = validateEntry(invalidEntry1);
|
||||||
|
expect(isValid1).toBe(false);
|
||||||
|
|
||||||
|
// Invalid action string (not in enum)
|
||||||
|
const invalidEntry2 = {
|
||||||
|
timestamp: validTimestamp,
|
||||||
|
action: 'INVALID_ACTION' as AuditAction,
|
||||||
|
status: AuditStatus.SUCCESS,
|
||||||
|
};
|
||||||
|
|
||||||
|
const isValid2 = validateEntry(invalidEntry2);
|
||||||
|
expect(isValid2).toBe(false);
|
||||||
|
|
||||||
|
// Missing required fields
|
||||||
|
const invalidEntry3 = {
|
||||||
|
timestamp: validTimestamp,
|
||||||
|
};
|
||||||
|
|
||||||
|
const isValid3 = validateEntry(invalidEntry3);
|
||||||
|
expect(isValid3).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Helper to validate an entry against the audit schema.
|
||||||
|
*/
|
||||||
|
function validateEntry(entry: unknown): boolean {
|
||||||
|
if (typeof entry !== 'object' || entry === null) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
const e = entry as Record<string, unknown>;
|
||||||
|
|
||||||
|
// Check required fields
|
||||||
|
if (typeof e.timestamp !== 'string' || Number.isNaN(Date.parse(e.timestamp))) return false;
|
||||||
|
if (!e.action || typeof e.action !== 'string') return false;
|
||||||
|
if (!e.status || typeof e.status !== 'string') return false;
|
||||||
|
|
||||||
|
// Validate action enum
|
||||||
|
const validActions = Object.values(AuditAction);
|
||||||
|
if (!validActions.includes(e.action as AuditAction)) return false;
|
||||||
|
|
||||||
|
// Validate status enum
|
||||||
|
const validStatuses = Object.values(AuditStatus);
|
||||||
|
if (!validStatuses.includes(e.status as AuditStatus)) return false;
|
||||||
|
|
||||||
|
// Actor and resource are optional but must be strings if present
|
||||||
|
if (e.actor !== undefined && typeof e.actor !== 'string') return false;
|
||||||
|
if (e.resource !== undefined && typeof e.resource !== 'string') return false;
|
||||||
|
|
||||||
|
// Details must be an object or undefined
|
||||||
|
if (e.details !== undefined && typeof e.details !== 'object') return false;
|
||||||
|
|
||||||
|
return true;
|
||||||
|
}
|
||||||
@@ -0,0 +1,127 @@
|
|||||||
|
/**
|
||||||
|
* Unit tests for bridge contracts (schemas, types, errors).
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { DeviceSchema, DeviceGroupSchema, DiagnosticResultSchema } from '../contracts';
|
||||||
|
|
||||||
|
describe('Contracts - Schemas', () => {
|
||||||
|
describe('DeviceSchema', () => {
|
||||||
|
it('should validate a complete device object', () => {
|
||||||
|
const validDevice = {
|
||||||
|
id: 'dev-001',
|
||||||
|
name: 'test-server',
|
||||||
|
groupId: 'grp-servers',
|
||||||
|
groupName: 'Servers',
|
||||||
|
status: 'online',
|
||||||
|
os: 'Ubuntu 24.04 LTS',
|
||||||
|
uptimeSeconds: 86400,
|
||||||
|
lastSeen: '2026-08-24T10:00:00Z',
|
||||||
|
ipAddresses: ['192.168.1.10'],
|
||||||
|
agentVersion: '2.4.1',
|
||||||
|
};
|
||||||
|
|
||||||
|
const result = DeviceSchema.safeParse(validDevice);
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should validate a minimal device object', () => {
|
||||||
|
const minimalDevice = {
|
||||||
|
id: 'dev-002',
|
||||||
|
name: 'minimal-device',
|
||||||
|
groupId: 'grp-devices',
|
||||||
|
groupName: 'Devices',
|
||||||
|
status: 'offline',
|
||||||
|
};
|
||||||
|
|
||||||
|
const result = DeviceSchema.safeParse(minimalDevice);
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should reject invalid status', () => {
|
||||||
|
const invalidDevice = {
|
||||||
|
id: 'dev-001',
|
||||||
|
name: 'test-server',
|
||||||
|
groupId: 'grp-servers',
|
||||||
|
groupName: 'Servers',
|
||||||
|
status: 'unknown-status' as const,
|
||||||
|
};
|
||||||
|
|
||||||
|
const result = DeviceSchema.safeParse(invalidDevice);
|
||||||
|
expect(result.success).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should validate device status enum values', () => {
|
||||||
|
const statuses = ['online', 'offline', 'unknown'];
|
||||||
|
for (const status of statuses) {
|
||||||
|
const device = {
|
||||||
|
id: `dev-${status}`,
|
||||||
|
name: `device-${status}`,
|
||||||
|
groupId: 'grp-test',
|
||||||
|
groupName: 'Test',
|
||||||
|
status,
|
||||||
|
};
|
||||||
|
const result = DeviceSchema.safeParse(device);
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('DeviceGroupSchema', () => {
|
||||||
|
it('should validate a complete group object', () => {
|
||||||
|
const validGroup = {
|
||||||
|
id: 'grp-servers',
|
||||||
|
name: 'Servers',
|
||||||
|
description: 'Production servers',
|
||||||
|
deviceCount: 10,
|
||||||
|
};
|
||||||
|
|
||||||
|
const result = DeviceGroupSchema.safeParse(validGroup);
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should validate a minimal group object', () => {
|
||||||
|
const minimalGroup = {
|
||||||
|
id: 'grp-devices',
|
||||||
|
name: 'Devices',
|
||||||
|
deviceCount: 5,
|
||||||
|
};
|
||||||
|
|
||||||
|
const result = DeviceGroupSchema.safeParse(minimalGroup);
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('DiagnosticResultSchema', () => {
|
||||||
|
it('should validate a complete diagnostic result', () => {
|
||||||
|
const validResult = {
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: 'diskSpace',
|
||||||
|
timestamp: '2026-08-24T10:00:00Z',
|
||||||
|
success: true,
|
||||||
|
output: 'Filesystem Size Used Avail Use% ...\n',
|
||||||
|
exitCode: 0,
|
||||||
|
outputLength: 1234,
|
||||||
|
maxOutputLength: 65_536,
|
||||||
|
};
|
||||||
|
|
||||||
|
const result = DiagnosticResultSchema.safeParse(validResult);
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should validate with truncated flag', () => {
|
||||||
|
const result = DiagnosticResultSchema.safeParse({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: 'diskSpace',
|
||||||
|
timestamp: '2026-08-24T10:00:00Z',
|
||||||
|
success: true,
|
||||||
|
output: 'truncated output...',
|
||||||
|
exitCode: 0,
|
||||||
|
outputLength: 65_536,
|
||||||
|
maxOutputLength: 65_536,
|
||||||
|
truncated: true,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,73 @@
|
|||||||
|
/**
|
||||||
|
* Tests for device status handling.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { createMockAdapter } from '../index';
|
||||||
|
|
||||||
|
describe('Device Status', () => {
|
||||||
|
let adapter: ReturnType<typeof createMockAdapter>;
|
||||||
|
|
||||||
|
beforeEach(() => {
|
||||||
|
adapter = createMockAdapter();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should include all device statuses in mock data', async () => {
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
|
||||||
|
const statuses = devices.map((d: { status: string }) => d.status);
|
||||||
|
expect(statuses).toContain('online');
|
||||||
|
expect(statuses).toContain('offline');
|
||||||
|
|
||||||
|
// Verify status enum values
|
||||||
|
for (const device of devices) {
|
||||||
|
expect(['online', 'offline', 'unknown']).toContain(device.status);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle offline devices correctly', async () => {
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
const offlineDevice = devices.find((d: { status: string }) => d.status === 'offline');
|
||||||
|
|
||||||
|
expect(offlineDevice).toBeDefined();
|
||||||
|
|
||||||
|
// Offline devices should still be retrievable
|
||||||
|
if (offlineDevice) {
|
||||||
|
const detailed = await adapter.getDevice(offlineDevice.id);
|
||||||
|
expect(detailed.status).toBe('offline');
|
||||||
|
// Uptime may not be available for offline devices
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should include lastSeen timestamp', async () => {
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
|
||||||
|
for (const device of devices) {
|
||||||
|
expect(device.lastSeen).toBeDefined();
|
||||||
|
// Verify ISO 8601 format
|
||||||
|
expect(Date.parse(device.lastSeen!)).toBeGreaterThan(0);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should include IP addresses when available', async () => {
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
|
||||||
|
// At least some devices should have IP addresses
|
||||||
|
const devicesWithIPs = devices.filter((d: { ipAddresses?: string[] }) => d.ipAddresses && d.ipAddresses.length > 0);
|
||||||
|
expect(devicesWithIPs.length).toBeGreaterThan(0);
|
||||||
|
|
||||||
|
// Verify IP format
|
||||||
|
for (const device of devicesWithIPs) {
|
||||||
|
if (device.ipAddresses) {
|
||||||
|
for (const ip of device.ipAddresses) {
|
||||||
|
expect(typeof ip).toBe('string');
|
||||||
|
// Basic IP address format validation
|
||||||
|
if (ip.includes(':')) {
|
||||||
|
expect(ip).toMatch(/^[0-9a-fA-F:]+$/); // IPv6
|
||||||
|
} else {
|
||||||
|
expect(ip).toMatch(/^\d+\.\d+\.\d+\.\d+$/); // IPv4
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
{
|
||||||
|
"devices": [
|
||||||
|
{
|
||||||
|
"id": "dev-001",
|
||||||
|
"name": "home-server",
|
||||||
|
"groupId": "grp-servers",
|
||||||
|
"groupName": "Servers",
|
||||||
|
"status": "online",
|
||||||
|
"os": "Ubuntu 24.04 LTS",
|
||||||
|
"uptimeSeconds": 1296000,
|
||||||
|
"lastSeen": "2026-08-24T21:30:00Z",
|
||||||
|
"ipAddresses": ["192.168.1.10", "fd00::1"],
|
||||||
|
"agentVersion": "2.4.1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "dev-002",
|
||||||
|
"name": "proxmox-prod",
|
||||||
|
"groupId": "grp-servers",
|
||||||
|
"groupName": "Servers",
|
||||||
|
"status": "online",
|
||||||
|
"os": "Proxmox VE 8.2",
|
||||||
|
"uptimeSeconds": 259200,
|
||||||
|
"lastSeen": "2026-08-24T21:28:00Z",
|
||||||
|
"ipAddresses": ["192.168.1.13", "fd00::2"],
|
||||||
|
"agentVersion": "2.4.1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "dev-003",
|
||||||
|
"name": "test-lab-client",
|
||||||
|
"groupId": "grp-workstations",
|
||||||
|
"groupName": "Workstations",
|
||||||
|
"status": "offline",
|
||||||
|
"os": "Windows 11 Pro",
|
||||||
|
"lastSeen": "2026-08-23T21:30:00Z",
|
||||||
|
"ipAddresses": ["192.168.1.50"],
|
||||||
|
"agentVersion": "2.4.1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "dev-004",
|
||||||
|
"name": "raspberry-pi-01",
|
||||||
|
"groupId": "grp-devices",
|
||||||
|
"groupName": "IoT Devices",
|
||||||
|
"status": "online",
|
||||||
|
"os": "Raspberry Pi OS 12 (Bookworm)",
|
||||||
|
"uptimeSeconds": 604800,
|
||||||
|
"lastSeen": "2026-08-24T21:35:00Z",
|
||||||
|
"ipAddresses": ["192.168.1.100"],
|
||||||
|
"agentVersion": "2.4.1"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"groups": [
|
||||||
|
{
|
||||||
|
"id": "grp-servers",
|
||||||
|
"name": "Servers",
|
||||||
|
"description": "Production and infrastructure servers",
|
||||||
|
"deviceCount": 2
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "grp-workstations",
|
||||||
|
"name": "Workstations",
|
||||||
|
"description": "User workstations and laptops",
|
||||||
|
"deviceCount": 1
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "grp-devices",
|
||||||
|
"name": "IoT Devices",
|
||||||
|
"description": "Raspberry Pi and other IoT devices",
|
||||||
|
"deviceCount": 1
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
/**
|
||||||
|
* Tests for group filtering functionality.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { createMockAdapter } from '../mock-adapter';
|
||||||
|
|
||||||
|
describe('Group Filtering', () => {
|
||||||
|
let adapter: ReturnType<typeof createMockAdapter>;
|
||||||
|
|
||||||
|
beforeEach(() => {
|
||||||
|
adapter = createMockAdapter();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should list groups with correct device counts', async () => {
|
||||||
|
const groups = await adapter.listGroups();
|
||||||
|
|
||||||
|
expect(groups).toHaveLength(3);
|
||||||
|
|
||||||
|
// Verify device counts match actual devices in each group
|
||||||
|
for (const group of groups) {
|
||||||
|
const devices = await adapter.listDevices({ groupId: group.id });
|
||||||
|
expect(devices.length).toBe(group.deviceCount);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should filter devices by group ID', async () => {
|
||||||
|
const groups = await adapter.listGroups();
|
||||||
|
const serversGroup = groups.find((g) => g.name === 'Servers');
|
||||||
|
|
||||||
|
expect(serversGroup).toBeDefined();
|
||||||
|
|
||||||
|
if (serversGroup) {
|
||||||
|
const devices = await adapter.listDevices({ groupId: serversGroup.id });
|
||||||
|
expect(devices).toHaveLength(2);
|
||||||
|
expect(devices.every((d) => d.groupId === serversGroup.id)).toBe(true);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return empty array for non-existent group', async () => {
|
||||||
|
const devices = await adapter.listDevices({ groupId: 'nonexistent' });
|
||||||
|
expect(devices).toHaveLength(0);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should include group name in device objects', async () => {
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
|
||||||
|
for (const device of devices) {
|
||||||
|
expect(device.groupName).toBeDefined();
|
||||||
|
expect(typeof device.groupName).toBe('string');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,137 @@
|
|||||||
|
/**
|
||||||
|
* Integration tests that validate the full bridge workflow.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { createMeshCentralAdapter, DiagnosticCheckType } from '../index';
|
||||||
|
|
||||||
|
describe('Bridge Integration', () => {
|
||||||
|
let adapter: ReturnType<typeof createMeshCentralAdapter>;
|
||||||
|
|
||||||
|
beforeEach(() => {
|
||||||
|
adapter = createMeshCentralAdapter({ adapterType: 'mock' });
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Device Discovery Workflow', () => {
|
||||||
|
it('should list all devices and groups, then fetch device details', async () => {
|
||||||
|
// Step 1: List all devices
|
||||||
|
const allDevices = await adapter.listDevices();
|
||||||
|
expect(allDevices).toHaveLength(4);
|
||||||
|
|
||||||
|
// Step 2: Get a specific device
|
||||||
|
const serverDevice = allDevices.find((d) => d.groupId === 'grp-servers');
|
||||||
|
if (!serverDevice) {
|
||||||
|
throw new Error('No server device found for testing');
|
||||||
|
}
|
||||||
|
|
||||||
|
const detailedDevice = await adapter.getDevice(serverDevice.id);
|
||||||
|
expect(detailedDevice.name).toBe(serverDevice.name);
|
||||||
|
|
||||||
|
// Step 3: Verify device belongs to expected group
|
||||||
|
expect(detailedDevice.groupId).toBe('grp-servers');
|
||||||
|
|
||||||
|
const group = await adapter.getGroup(detailedDevice.groupId);
|
||||||
|
expect(group.name).toBe('Servers');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle offline devices gracefully', async () => {
|
||||||
|
const allDevices = await adapter.listDevices();
|
||||||
|
const offlineDevices = allDevices.filter((d: { status: string }) => d.status === 'offline');
|
||||||
|
|
||||||
|
expect(offlineDevices).toHaveLength(1);
|
||||||
|
const offlineDevice = offlineDevices[0];
|
||||||
|
|
||||||
|
// Offline devices should still be retrievable
|
||||||
|
const detailed = await adapter.getDevice(offlineDevice.id);
|
||||||
|
expect(detailed.status).toBe('offline');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Diagnostics Workflow', () => {
|
||||||
|
it('should run multiple diagnostic checks on a device', async () => {
|
||||||
|
const testDeviceId = 'dev-001';
|
||||||
|
|
||||||
|
const checks: DiagnosticCheckType[] = [
|
||||||
|
DiagnosticCheckType.DiskSpace,
|
||||||
|
DiagnosticCheckType.OSDetails,
|
||||||
|
DiagnosticCheckType.Uptime,
|
||||||
|
];
|
||||||
|
|
||||||
|
for (const checkType of checks) {
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: testDeviceId,
|
||||||
|
checkType,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
expect(result.exitCode).toBe(0);
|
||||||
|
expect(result.output.length).toBeGreaterThan(0);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle diagnostics on offline devices', async () => {
|
||||||
|
const offlineDevice = await adapter.getDevice('dev-003');
|
||||||
|
expect(offlineDevice.status).toBe('offline');
|
||||||
|
|
||||||
|
// Diagnostics should still run (mock returns consistent data)
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: offlineDevice.id,
|
||||||
|
checkType: DiagnosticCheckType.OSDetails,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Error Handling', () => {
|
||||||
|
it('should provide clear error messages for missing resources', async () => {
|
||||||
|
await expect(adapter.getDevice('nonexistent-device'))
|
||||||
|
.rejects
|
||||||
|
.toThrow('Device not found: nonexistent-device');
|
||||||
|
|
||||||
|
await expect(adapter.getGroup('nonexistent-group'))
|
||||||
|
.rejects
|
||||||
|
.toThrow('Group not found: nonexistent-group');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should include error codes in exceptions', async () => {
|
||||||
|
try {
|
||||||
|
await adapter.getDevice('nonexistent');
|
||||||
|
} catch (error: unknown) {
|
||||||
|
expect(error).toBeInstanceOf(Error);
|
||||||
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||||
|
expect((error as any).code).toBe('RESOURCE_NOT_FOUND');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Health Check', () => {
|
||||||
|
it('should report adapter health status', async () => {
|
||||||
|
const healthy = await adapter.healthCheck();
|
||||||
|
expect(healthy).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Output Limits', () => {
|
||||||
|
it('should truncate large output when maxOutputLength is specified', async () => {
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
maxOutputLength: 100,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.truncated).toBe(true);
|
||||||
|
expect(result.output.length).toBeLessThan(200); // 100 + truncation marker
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should report output length and truncation status', async () => {
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
maxOutputLength: 500,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.outputLength).toBeGreaterThan(0);
|
||||||
|
expect(result.maxOutputLength).toBe(500);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,14 @@
|
|||||||
|
describe('live read-only test safety contract', () => {
|
||||||
|
it('does not expose a general-purpose command or diagnostic action', async () => {
|
||||||
|
const source = await import('node:fs').then(({ readFileSync }) =>
|
||||||
|
readFileSync(require.resolve('../live-readonly-test'), 'utf8'));
|
||||||
|
expect(source).toContain("MeshCtrlAction.ServerVersion");
|
||||||
|
expect(source).toContain("MeshCtrlAction.Meshes");
|
||||||
|
expect(source).toContain("MeshCtrlAction.Nodes");
|
||||||
|
expect(source).toContain("MeshCtrlAction.DeviceInfo");
|
||||||
|
expect(source).toContain("nodeid: approvedDevice.id");
|
||||||
|
expect(source).not.toContain('runcommand');
|
||||||
|
expect(source).not.toContain('diagnostic');
|
||||||
|
expect(source).not.toContain('process.argv');
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,245 @@
|
|||||||
|
/**
|
||||||
|
* Unit tests for bounded request concurrency and rate limiting in MeshCtrlClient.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { TokenBucket, ConcurrencyLimiter } from '../meshctrl-client';
|
||||||
|
|
||||||
|
describe('ConcurrencyLimiter safe defaults', () => {
|
||||||
|
it('should have a safe default of 5 max concurrent requests', () => {
|
||||||
|
const limiter = new ConcurrencyLimiter();
|
||||||
|
expect(limiter.getMaxPending()).toBe(5);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should allow entry up to the safe default', () => {
|
||||||
|
const limiter = new ConcurrencyLimiter();
|
||||||
|
for (let i = 0; i < 5; i++) {
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
}
|
||||||
|
// 6th should fail
|
||||||
|
expect(limiter.tryEnter()).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('TokenBucket rate limiter', () => {
|
||||||
|
describe('acquire()', () => {
|
||||||
|
it('should consume tokens and return true when available', () => {
|
||||||
|
const bucket = new TokenBucket(5, 0.01, 30_000); // Minimum valid refill rate
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return false when no tokens are available', () => {
|
||||||
|
const bucket = new TokenBucket(2, 0.01, 30_000); // Minimum valid refill rate
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
// Force reset to ensure no tokens left
|
||||||
|
(bucket as unknown as { tokens: number }).tokens = 0;
|
||||||
|
expect(bucket.acquire()).toBe(false); // No tokens left
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should refill tokens over time based on rate', async () => {
|
||||||
|
// Create bucket with 2 tokens, refill at 1 token/second
|
||||||
|
const bucket = new TokenBucket(2, 1, 30_000);
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(bucket.acquire()).toBe(false);
|
||||||
|
|
||||||
|
// Wait 1.5 seconds for ~1.5 tokens to refill
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, 1500));
|
||||||
|
|
||||||
|
// Should be able to acquire again
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should respect maxTokens limit on refill', async () => {
|
||||||
|
const bucket = new TokenBucket(3, 0.01, 30_000); // Minimum valid refill rate
|
||||||
|
// Consume all tokens
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
|
||||||
|
// Force set tokens to 0 and lastRefill to now to prevent refilling during test
|
||||||
|
(bucket as unknown as { tokens: number; lastRefill: number }).tokens = 0;
|
||||||
|
(bucket as unknown as { tokens: number; lastRefill: number }).lastRefill = Date.now();
|
||||||
|
|
||||||
|
expect(bucket.acquire()).toBe(false); // No tokens left
|
||||||
|
|
||||||
|
// Wait for more than enough time (50ms -> 0.05 tokens at 0.01/sec, still < 1)
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, 50));
|
||||||
|
|
||||||
|
// Should not have gained any tokens due to very slow refill rate
|
||||||
|
expect(bucket.acquire()).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('acquireWithWait()', () => {
|
||||||
|
it('should resolve immediately when tokens are available', async () => {
|
||||||
|
const bucket = new TokenBucket(5, 10, 30_000);
|
||||||
|
const start = Date.now();
|
||||||
|
await bucket.acquireWithWait();
|
||||||
|
const elapsed = Date.now() - start;
|
||||||
|
expect(elapsed).toBeLessThan(10); // Should be nearly instant
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should wait for tokens and resolve when available', async () => {
|
||||||
|
const bucket = new TokenBucket(1, 10, 30_000); // 1 token, refill at 10/sec
|
||||||
|
bucket.acquire(); // Consume the only token
|
||||||
|
|
||||||
|
const start = Date.now();
|
||||||
|
await bucket.acquireWithWait(); // Should wait ~100ms for refill
|
||||||
|
const elapsed = Date.now() - start;
|
||||||
|
|
||||||
|
expect(elapsed).toBeGreaterThanOrEqual(50); // Allow some timing variance
|
||||||
|
expect(elapsed).toBeLessThan(300);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should reject on timeout', async () => {
|
||||||
|
const bucket = new TokenBucket(1, 1, 100); // 1 token, refill at 1/sec, timeout after 100ms
|
||||||
|
bucket.acquire(); // Consume the only token
|
||||||
|
|
||||||
|
await expect(bucket.acquireWithWait()).rejects.toThrow(/Rate limit wait timeout/);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('integration with MeshCtrlClient options', () => {
|
||||||
|
it('should accept rate limit configuration via options', async () => {
|
||||||
|
// Test that the types are properly exported and usable
|
||||||
|
const config = {
|
||||||
|
maxRequestsPerSecond: 5,
|
||||||
|
burstCapacity: 3,
|
||||||
|
rateLimitTimeoutMs: 5000,
|
||||||
|
};
|
||||||
|
expect(config.maxRequestsPerSecond).toBe(5);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('ConcurrencyLimiter semaphore', () => {
|
||||||
|
describe('tryEnter()', () => {
|
||||||
|
it('should allow entry up to maxPending', () => {
|
||||||
|
const limiter = new ConcurrencyLimiter(2);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
expect(limiter.tryEnter()).toBe(false); // At capacity
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should track pending count correctly', () => {
|
||||||
|
const limiter = new ConcurrencyLimiter(3);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
expect(limiter.pendingCount).toBe(1);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
expect(limiter.pendingCount).toBe(2);
|
||||||
|
limiter.exit();
|
||||||
|
expect(limiter.pendingCount).toBe(1);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('enter() and exit()', () => {
|
||||||
|
it('should block until slot is available', async () => {
|
||||||
|
const limiter = new ConcurrencyLimiter(1);
|
||||||
|
await limiter.enter();
|
||||||
|
|
||||||
|
let entered = false;
|
||||||
|
const enterPromise = limiter.enter().then(() => { entered = true; });
|
||||||
|
|
||||||
|
// Should not have entered yet
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, 50));
|
||||||
|
expect(entered).toBe(false);
|
||||||
|
|
||||||
|
// Exit to allow the waiting caller
|
||||||
|
limiter.exit();
|
||||||
|
await enterPromise;
|
||||||
|
expect(entered).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should properly exit slots', () => {
|
||||||
|
const limiter = new ConcurrencyLimiter(2);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
limiter.exit();
|
||||||
|
expect(limiter.pendingCount).toBe(1);
|
||||||
|
limiter.exit();
|
||||||
|
expect(limiter.pendingCount).toBe(0);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('integration with MeshCtrlClient options', () => {
|
||||||
|
it('should accept concurrency configuration via options', async () => {
|
||||||
|
const config = {
|
||||||
|
maxConcurrentRequests: 10,
|
||||||
|
};
|
||||||
|
expect(config.maxConcurrentRequests).toBe(10);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('TokenBucket + ConcurrencyLimiter combined', () => {
|
||||||
|
it('should work together for rate limiting and concurrency control', async () => {
|
||||||
|
const bucket = new TokenBucket(2, 10, 30_000);
|
||||||
|
const limiter = new ConcurrencyLimiter(2);
|
||||||
|
|
||||||
|
// Both should allow 2 initial operations
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
expect(bucket.acquire()).toBe(true);
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
|
||||||
|
// Both should be at capacity
|
||||||
|
expect(bucket.acquire()).toBe(false);
|
||||||
|
expect(limiter.tryEnter()).toBe(false);
|
||||||
|
|
||||||
|
// Exit one from each
|
||||||
|
limiter.exit();
|
||||||
|
expect(limiter.tryEnter()).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('concurrency with async enter/exit', () => {
|
||||||
|
it('should properly serialize concurrent requests when using async enter', async () => {
|
||||||
|
const limiter = new ConcurrencyLimiter(2);
|
||||||
|
let concurrentCount = 0;
|
||||||
|
let maxConcurrent = 0;
|
||||||
|
|
||||||
|
const simulateRequest = async (_id: number): Promise<void> => {
|
||||||
|
await limiter.enter();
|
||||||
|
concurrentCount++;
|
||||||
|
maxConcurrent = Math.max(maxConcurrent, concurrentCount);
|
||||||
|
|
||||||
|
// Simulate some async work
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, 10));
|
||||||
|
|
||||||
|
concurrentCount--;
|
||||||
|
limiter.exit();
|
||||||
|
};
|
||||||
|
|
||||||
|
// Launch 5 concurrent requests
|
||||||
|
const promises = Array.from({ length: 5 }, (_, i) => simulateRequest(i));
|
||||||
|
await Promise.all(promises);
|
||||||
|
|
||||||
|
// Should never exceed maxPending (2)
|
||||||
|
expect(maxConcurrent).toBeLessThanOrEqual(2);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle rapid enter/exit cycles without deadlock', async () => {
|
||||||
|
const limiter = new ConcurrencyLimiter(3);
|
||||||
|
let completed = 0;
|
||||||
|
|
||||||
|
const processItem = async (_id: number): Promise<void> => {
|
||||||
|
await limiter.enter();
|
||||||
|
try {
|
||||||
|
// Simulate quick work
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, 5));
|
||||||
|
completed++;
|
||||||
|
} finally {
|
||||||
|
limiter.exit();
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Process 10 items with limited concurrency
|
||||||
|
const promises = Array.from({ length: 10 }, (_, i) => processItem(i));
|
||||||
|
await Promise.all(promises);
|
||||||
|
|
||||||
|
expect(completed).toBe(10);
|
||||||
|
expect(limiter.pendingCount).toBe(0); // All slots released
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
import {
|
||||||
|
MeshCtrlAction,
|
||||||
|
encodeAuthHeader,
|
||||||
|
parseResponse,
|
||||||
|
sanitizeCredentials,
|
||||||
|
validateResponseForAction,
|
||||||
|
} from '../meshctrl-client';
|
||||||
|
|
||||||
|
describe('MeshCtrl client protocol validation', () => {
|
||||||
|
it('encodes valid credentials without exposing them in the returned metadata', () => {
|
||||||
|
expect(encodeAuthHeader({ username: 'bridge-user', password: 'strong-pass' })).toBe(
|
||||||
|
`${Buffer.from('bridge-user').toString('base64')},${Buffer.from('strong-pass').toString('base64')}`,
|
||||||
|
);
|
||||||
|
expect(encodeAuthHeader({ username: 'bridge-user', password: 'strong-pass', totpToken: '123456' })).toBe(
|
||||||
|
`${Buffer.from('bridge-user').toString('base64')},${Buffer.from('strong-pass').toString('base64')},${Buffer.from('123456').toString('base64')}`,
|
||||||
|
);
|
||||||
|
expect(sanitizeCredentials({ username: 'bridge-user', password: 'strong-pass' })).toEqual({
|
||||||
|
hasCredentials: true,
|
||||||
|
redacted: true,
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it('rejects malformed credentials', () => {
|
||||||
|
expect(() => encodeAuthHeader({ username: 'bad user', password: 'strong-pass' })).toThrow();
|
||||||
|
expect(() => encodeAuthHeader({ username: 'bridge-user', password: 'short' })).toThrow();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('rejects malformed and oversized protocol responses', () => {
|
||||||
|
expect(() => parseResponse('{"id":1}')).toThrow(/protocol validation/);
|
||||||
|
expect(() => parseResponse('x'.repeat(20), 10)).toThrow(/size limit/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('validates the response shape and action', () => {
|
||||||
|
const response = parseResponse(JSON.stringify({
|
||||||
|
action: MeshCtrlAction.ServerVersion,
|
||||||
|
id: 1,
|
||||||
|
ver: '1.2.5',
|
||||||
|
}));
|
||||||
|
expect(validateResponseForAction(response, MeshCtrlAction.ServerVersion)).toEqual(response);
|
||||||
|
expect(() => validateResponseForAction(response, MeshCtrlAction.Nodes)).toThrow(/action/);
|
||||||
|
expect(() => validateResponseForAction(parseResponse(JSON.stringify({
|
||||||
|
action: MeshCtrlAction.Nodes,
|
||||||
|
id: 1,
|
||||||
|
nodes: [{ id: 'n1', name: 'node', meshid: 'm1', online: 'yes' }],
|
||||||
|
})), MeshCtrlAction.Nodes)).toThrow(/schema/);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,167 @@
|
|||||||
|
/**
|
||||||
|
* Unit tests for the mock adapter.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { createMockAdapter, DiagnosticCheckType } from '../index';
|
||||||
|
|
||||||
|
describe('MockAdapter', () => {
|
||||||
|
let adapter: ReturnType<typeof createMockAdapter>;
|
||||||
|
|
||||||
|
beforeEach(() => {
|
||||||
|
adapter = createMockAdapter();
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('listDevices', () => {
|
||||||
|
it('should return all devices when no filter provided', async () => {
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
expect(devices).toHaveLength(4);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should filter by group ID', async () => {
|
||||||
|
const devices = await adapter.listDevices({ groupId: 'grp-servers' });
|
||||||
|
expect(devices).toHaveLength(2);
|
||||||
|
expect(devices.every((d: { groupId: string }) => d.groupId === 'grp-servers')).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return empty array for non-existent group', async () => {
|
||||||
|
const devices = await adapter.listDevices({ groupId: 'nonexistent' });
|
||||||
|
expect(devices).toHaveLength(0);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should include expected device properties', async () => {
|
||||||
|
const devices = await adapter.listDevices();
|
||||||
|
const device = devices[0];
|
||||||
|
|
||||||
|
expect(device).toMatchObject({
|
||||||
|
id: expect.any(String),
|
||||||
|
name: expect.any(String),
|
||||||
|
groupId: expect.any(String),
|
||||||
|
groupName: expect.any(String),
|
||||||
|
status: expect.stringMatching(/online|offline|unknown/),
|
||||||
|
});
|
||||||
|
|
||||||
|
// Properties that may be undefined for offline devices
|
||||||
|
expect(device.os).toBeDefined();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getDevice', () => {
|
||||||
|
it('should return a specific device by ID', async () => {
|
||||||
|
const device = await adapter.getDevice('dev-001');
|
||||||
|
expect(device.id).toBe('dev-001');
|
||||||
|
expect(device.name).toBe('home-server');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error for non-existent device', async () => {
|
||||||
|
await expect(adapter.getDevice('nonexistent')).rejects.toThrow('Device not found');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('listGroups', () => {
|
||||||
|
it('should return all groups', async () => {
|
||||||
|
const groups = await adapter.listGroups();
|
||||||
|
expect(groups).toHaveLength(3);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should include expected group properties', async () => {
|
||||||
|
const groups = await adapter.listGroups();
|
||||||
|
const group = groups[0];
|
||||||
|
|
||||||
|
expect(group).toMatchObject({
|
||||||
|
id: expect.any(String),
|
||||||
|
name: expect.any(String),
|
||||||
|
deviceCount: expect.any(Number),
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getGroup', () => {
|
||||||
|
it('should return a specific group by ID', async () => {
|
||||||
|
const group = await adapter.getGroup('grp-servers');
|
||||||
|
expect(group.id).toBe('grp-servers');
|
||||||
|
expect(group.name).toBe('Servers');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error for non-existent group', async () => {
|
||||||
|
await expect(adapter.getGroup('nonexistent')).rejects.toThrow('Group not found');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('runDiagnostic', () => {
|
||||||
|
it('should return diagnostic result for diskSpace check', async () => {
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result).toMatchObject({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
success: true,
|
||||||
|
exitCode: 0,
|
||||||
|
outputLength: expect.any(Number),
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.output).toContain('Filesystem');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should support all diagnostic check types', async () => {
|
||||||
|
const checkTypes = [
|
||||||
|
DiagnosticCheckType.DiskSpace,
|
||||||
|
DiagnosticCheckType.Services,
|
||||||
|
DiagnosticCheckType.Processes,
|
||||||
|
DiagnosticCheckType.OSDetails,
|
||||||
|
DiagnosticCheckType.NetworkState,
|
||||||
|
DiagnosticCheckType.Uptime,
|
||||||
|
];
|
||||||
|
|
||||||
|
for (const checkType of checkTypes) {
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.checkType).toBe(checkType);
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should truncate output when maxOutputLength is exceeded', async () => {
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
maxOutputLength: 50,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.truncated).toBe(true);
|
||||||
|
expect(result.output.length).toBeLessThan(200); // 50 + truncation marker
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should respect timeoutMs parameter', async () => {
|
||||||
|
const startTime = Date.now();
|
||||||
|
await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
timeoutMs: 50,
|
||||||
|
});
|
||||||
|
const elapsed = Date.now() - startTime;
|
||||||
|
|
||||||
|
// Should complete within timeout + small buffer
|
||||||
|
expect(elapsed).toBeLessThan(100);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('healthCheck', () => {
|
||||||
|
it('should return true for mock adapter', async () => {
|
||||||
|
const healthy = await adapter.healthCheck();
|
||||||
|
expect(healthy).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('adapter metadata', () => {
|
||||||
|
it('should have name and version properties', () => {
|
||||||
|
expect(adapter.name).toBe('mock');
|
||||||
|
expect(adapter.version).toBe('0.1.0');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,38 @@
|
|||||||
|
/**
|
||||||
|
* Tests for the mock data loader.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { loadTestDeviceData } from './mock-data-loader';
|
||||||
|
|
||||||
|
describe('MockDataLoader', () => {
|
||||||
|
it('should load test device data from JSON file', () => {
|
||||||
|
const data = loadTestDeviceData();
|
||||||
|
|
||||||
|
expect(Array.isArray(data.devices)).toBe(true);
|
||||||
|
expect(Array.isArray(data.groups)).toBe(true);
|
||||||
|
expect(data.devices.length).toBeGreaterThan(0);
|
||||||
|
expect(data.groups.length).toBeGreaterThan(0);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should load valid device structures', () => {
|
||||||
|
const data = loadTestDeviceData();
|
||||||
|
|
||||||
|
for (const device of data.devices) {
|
||||||
|
expect(typeof device.id).toBe('string');
|
||||||
|
expect(typeof device.name).toBe('string');
|
||||||
|
expect(typeof device.groupId).toBe('string');
|
||||||
|
expect(typeof device.groupName).toBe('string');
|
||||||
|
expect(['online', 'offline', 'unknown']).toContain(device.status);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should load valid group structures', () => {
|
||||||
|
const data = loadTestDeviceData();
|
||||||
|
|
||||||
|
for (const group of data.groups) {
|
||||||
|
expect(typeof group.id).toBe('string');
|
||||||
|
expect(typeof group.name).toBe('string');
|
||||||
|
expect(typeof group.deviceCount).toBe('number');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
/**
|
||||||
|
* Test data loader for consistent test fixtures.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { readFileSync } from 'fs';
|
||||||
|
import { join } from 'path';
|
||||||
|
|
||||||
|
export interface TestDeviceData {
|
||||||
|
devices: Array<{
|
||||||
|
id: string;
|
||||||
|
name: string;
|
||||||
|
groupId: string;
|
||||||
|
groupName: string;
|
||||||
|
status: 'online' | 'offline' | 'unknown';
|
||||||
|
os?: string;
|
||||||
|
uptimeSeconds?: number;
|
||||||
|
lastSeen?: string;
|
||||||
|
ipAddresses?: string[];
|
||||||
|
agentVersion?: string;
|
||||||
|
}>;
|
||||||
|
groups: Array<{
|
||||||
|
id: string;
|
||||||
|
name: string;
|
||||||
|
description?: string;
|
||||||
|
deviceCount: number;
|
||||||
|
}>;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function loadTestDeviceData(): TestDeviceData {
|
||||||
|
const dataPath = join(__dirname, 'example-device-data.json');
|
||||||
|
const content = readFileSync(dataPath, 'utf-8');
|
||||||
|
return JSON.parse(content) as TestDeviceData;
|
||||||
|
}
|
||||||
@@ -0,0 +1,41 @@
|
|||||||
|
/**
|
||||||
|
* Jest setup file.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import 'jest-extended';
|
||||||
|
|
||||||
|
declare global {
|
||||||
|
// eslint-disable-next-line @typescript-eslint/no-namespace
|
||||||
|
namespace jest {
|
||||||
|
interface Expect {
|
||||||
|
toBeArray(): void;
|
||||||
|
toBeString(): void;
|
||||||
|
toBeNumber(): void;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Custom matchers
|
||||||
|
expect.extend({
|
||||||
|
toBeArray(received: unknown) {
|
||||||
|
const pass = Array.isArray(received);
|
||||||
|
return {
|
||||||
|
message: () => `expected ${received} to be an array`,
|
||||||
|
pass,
|
||||||
|
};
|
||||||
|
},
|
||||||
|
toBeString(received: unknown) {
|
||||||
|
const pass = typeof received === 'string';
|
||||||
|
return {
|
||||||
|
message: () => `expected ${received} to be a string`,
|
||||||
|
pass,
|
||||||
|
};
|
||||||
|
},
|
||||||
|
toBeNumber(received: unknown) {
|
||||||
|
const pass = typeof received === 'number';
|
||||||
|
return {
|
||||||
|
message: () => `expected ${received} to be a number`,
|
||||||
|
pass,
|
||||||
|
};
|
||||||
|
},
|
||||||
|
});
|
||||||
@@ -0,0 +1,58 @@
|
|||||||
|
/**
|
||||||
|
* Tests for timeout and output limit handling.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { createMockAdapter, DiagnosticCheckType } from '../index';
|
||||||
|
|
||||||
|
describe('Timeout and Output Limits', () => {
|
||||||
|
it('should respect timeoutMs parameter', async () => {
|
||||||
|
const adapter = createMockAdapter({ timeoutMs: 100 });
|
||||||
|
|
||||||
|
const startTime = Date.now();
|
||||||
|
await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
timeoutMs: 50,
|
||||||
|
});
|
||||||
|
const elapsed = Date.now() - startTime;
|
||||||
|
|
||||||
|
expect(elapsed).toBeLessThan(100);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should truncate output when maxOutputLength is small', async () => {
|
||||||
|
const adapter = createMockAdapter({ maxOutputLength: 100 });
|
||||||
|
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
maxOutputLength: 50,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.truncated).toBe(true);
|
||||||
|
expect(result.output.length).toBeLessThan(200); // 50 + truncation marker
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should report maxOutputLength in result', async () => {
|
||||||
|
const adapter = createMockAdapter({ maxOutputLength: 65_536 });
|
||||||
|
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.maxOutputLength).toBe(65_536);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle zero timeout gracefully', async () => {
|
||||||
|
const adapter = createMockAdapter({ timeoutMs: 1000 });
|
||||||
|
|
||||||
|
// Zero or negative timeout should not cause errors
|
||||||
|
const result = await adapter.runDiagnostic({
|
||||||
|
deviceId: 'dev-001',
|
||||||
|
checkType: DiagnosticCheckType.DiskSpace,
|
||||||
|
timeoutMs: 0,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,708 @@
|
|||||||
|
/**
|
||||||
|
* Adapter pattern for MeshCentral integration.
|
||||||
|
*
|
||||||
|
* Defines the boundary where a real MeshCentral client can be swapped in.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import {
|
||||||
|
MeshCentralAdapter,
|
||||||
|
Device,
|
||||||
|
DeviceGroup,
|
||||||
|
DiagnosticResult,
|
||||||
|
ListDevicesRequest,
|
||||||
|
RunDiagnosticRequest,
|
||||||
|
BridgeError,
|
||||||
|
ErrorCodes,
|
||||||
|
defaultConfig,
|
||||||
|
BridgeConfig,
|
||||||
|
DeviceStatus,
|
||||||
|
validateCredentials,
|
||||||
|
} from './contracts';
|
||||||
|
import { createMockAdapter } from './mock-adapter';
|
||||||
|
import {
|
||||||
|
MeshCtrlClient,
|
||||||
|
} from './meshctrl-client';
|
||||||
|
import {
|
||||||
|
createAuditEntry,
|
||||||
|
AuditAction,
|
||||||
|
AuditStatus,
|
||||||
|
} from './audit';
|
||||||
|
import { Logger, getGlobalLogger } from './logger';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Real MeshCentral adapter using the official meshctrl.js protocol.
|
||||||
|
*
|
||||||
|
* Connects to MeshCentral's control.ashx WebSocket and uses the
|
||||||
|
* same protocol as meshctrl.js for inventory and diagnostics.
|
||||||
|
*/
|
||||||
|
export class MeshCentralRealAdapter implements MeshCentralAdapter {
|
||||||
|
readonly name = 'meshcentral-real';
|
||||||
|
readonly version = '0.1.0';
|
||||||
|
|
||||||
|
private config: BridgeConfig;
|
||||||
|
private client: MeshCtrlClient | null = null;
|
||||||
|
private credentials: { username: string; password: string; totpToken?: string } | null = null;
|
||||||
|
private connected = false;
|
||||||
|
private logger: Logger;
|
||||||
|
|
||||||
|
constructor(config?: Partial<BridgeConfig>) {
|
||||||
|
this.config = { ...defaultConfig, ...(config ?? {}) };
|
||||||
|
// Use a dedicated logger for this adapter instance
|
||||||
|
// In production, you could inject a custom logger via config
|
||||||
|
this.logger = getGlobalLogger();
|
||||||
|
// Set the logger name to be more descriptive
|
||||||
|
this.logger.setName('meshcentral-adapter');
|
||||||
|
|
||||||
|
// Validate configuration and credentials
|
||||||
|
this._validateConfig();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Set credentials for authentication.
|
||||||
|
* Must be called before connecting to the real adapter.
|
||||||
|
*/
|
||||||
|
setCredentials(credentials: { username: string; password: string; totpToken?: string }): void {
|
||||||
|
// Log audit entry for credential update attempt
|
||||||
|
this._auditLog(AuditAction.CREDENTIAL_UPDATE, AuditStatus.PENDING, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'adapter-credentials',
|
||||||
|
});
|
||||||
|
|
||||||
|
// Validate credentials before storing
|
||||||
|
validateCredentials(credentials);
|
||||||
|
|
||||||
|
this.credentials = {
|
||||||
|
username: credentials.username,
|
||||||
|
password: credentials.password,
|
||||||
|
totpToken: credentials.totpToken,
|
||||||
|
};
|
||||||
|
|
||||||
|
// Log successful credential update (redacted)
|
||||||
|
this._auditLog(AuditAction.CREDENTIAL_UPDATE, AuditStatus.SUCCESS, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'adapter-credentials',
|
||||||
|
detailsUpdated: true,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Generate a redacted credentials summary for logging.
|
||||||
|
*/
|
||||||
|
private _getCredentialsSummary(): { hasCredentials: boolean; hasTotp: boolean } {
|
||||||
|
if (!this.credentials) {
|
||||||
|
return { hasCredentials: false, hasTotp: false };
|
||||||
|
}
|
||||||
|
|
||||||
|
return {
|
||||||
|
hasCredentials: !!this.credentials.username && !!this.credentials.password,
|
||||||
|
hasTotp: !!this.credentials.totpToken,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get a safe actor name for audit logs (no secrets).
|
||||||
|
*/
|
||||||
|
private _getActorName(): string {
|
||||||
|
if (!this.credentials?.username) {
|
||||||
|
return 'unknown';
|
||||||
|
}
|
||||||
|
|
||||||
|
// Use username without exposing password or totp
|
||||||
|
return this.credentials.username;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Log an audit entry.
|
||||||
|
*/
|
||||||
|
private _auditLog(
|
||||||
|
action: AuditAction,
|
||||||
|
status: AuditStatus,
|
||||||
|
extraDetails?: Record<string, unknown>,
|
||||||
|
): void {
|
||||||
|
const details = {
|
||||||
|
adapter: this.name,
|
||||||
|
version: this.version,
|
||||||
|
configUrl: this.config.meshCentralUrl,
|
||||||
|
...extraDetails,
|
||||||
|
};
|
||||||
|
|
||||||
|
// Create and format audit entry (secrets already redacted by sanitizeForLogging)
|
||||||
|
const entry = createAuditEntry({
|
||||||
|
action,
|
||||||
|
status,
|
||||||
|
actor: typeof extraDetails?.actor === 'string' ? extraDetails.actor : this._getActorName(),
|
||||||
|
resource: typeof extraDetails?.resource === 'string'
|
||||||
|
? extraDetails.resource
|
||||||
|
: 'meshcentral-adapter',
|
||||||
|
details: Object.fromEntries(
|
||||||
|
Object.entries(details).filter(([key]) => key !== 'actor' && key !== 'resource'),
|
||||||
|
),
|
||||||
|
});
|
||||||
|
|
||||||
|
// Output audit log via structured logger
|
||||||
|
this.logger.audit(`AUDIT - ${entry.action} - ${entry.status}`, {
|
||||||
|
action: entry.action,
|
||||||
|
status: entry.status,
|
||||||
|
actor: typeof extraDetails?.actor === 'string' ? extraDetails.actor : this._getActorName(),
|
||||||
|
resource: typeof extraDetails?.resource === 'string'
|
||||||
|
? extraDetails.resource
|
||||||
|
: 'meshcentral-adapter',
|
||||||
|
...Object.fromEntries(
|
||||||
|
Object.entries(details).filter(([key]) => key !== 'actor' && key !== 'resource'),
|
||||||
|
),
|
||||||
|
});
|
||||||
|
|
||||||
|
if (process.env.AUDIT_DEBUG === 'true') {
|
||||||
|
this.logger.debug(JSON.stringify(entry, null, 2));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
private _validateConfig(): void {
|
||||||
|
// Log config load attempt
|
||||||
|
this._auditLog(AuditAction.CONFIG_LOAD, AuditStatus.PENDING, {
|
||||||
|
adapter: this.name,
|
||||||
|
resource: 'adapter-configuration',
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!this.config.meshCentralUrl) {
|
||||||
|
this._auditLog(AuditAction.CONFIG_LOAD, AuditStatus.FAILURE, {
|
||||||
|
adapter: this.name,
|
||||||
|
resource: 'adapter-configuration',
|
||||||
|
error: 'meshCentralUrl is required',
|
||||||
|
});
|
||||||
|
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Configuration is incomplete: meshCentralUrl is required',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check for credentials in environment/config
|
||||||
|
const hasUsername = !!this.config.username;
|
||||||
|
const hasPassword = !!this.config.password;
|
||||||
|
|
||||||
|
// Generic error message that doesn't reveal which credential is missing
|
||||||
|
if (hasUsername !== hasPassword) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Configuration is incomplete: authentication credentials must be provided together',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (this.config.adapterType === 'real' && (!hasUsername || !hasPassword)) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Real adapter requires authentication credentials',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Validate credential formats if present
|
||||||
|
if (hasUsername && hasPassword) {
|
||||||
|
try {
|
||||||
|
validateCredentials({
|
||||||
|
username: this.config.username,
|
||||||
|
password: this.config.password,
|
||||||
|
totpToken: this.config.totpToken,
|
||||||
|
});
|
||||||
|
} catch {
|
||||||
|
// Re-throw as generic error to prevent credential enumeration
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Authentication credentials are invalid',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Validate allowlist formats if provided
|
||||||
|
this._validateAllowlist(this.config.pveAllowlist, 'pveAllowlist');
|
||||||
|
this._validateAllowlist(this.config.deviceAllowlist, 'deviceAllowlist');
|
||||||
|
this._validateAllowlist(this.config.groupAllowlist, 'groupAllowlist');
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Validate allowlist entries.
|
||||||
|
*/
|
||||||
|
private _validateAllowlist(allowlist: string[] | undefined, name: string): void {
|
||||||
|
if (!allowlist) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
for (const entry of allowlist) {
|
||||||
|
if (!entry || typeof entry !== 'string' || entry.trim() === '') {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
`Allowlist entry in ${name} is empty or invalid`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if a device is in the allowlist.
|
||||||
|
*/
|
||||||
|
private _isDeviceAllowed(deviceId: string): boolean {
|
||||||
|
const { deviceAllowlist, groupAllowlist } = this.config;
|
||||||
|
|
||||||
|
// If no allowlists configured, all devices are allowed
|
||||||
|
if (!deviceAllowlist && !groupAllowlist) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check device allowlist first (specific devices)
|
||||||
|
if (deviceAllowlist && deviceAllowlist.includes(deviceId)) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
|
||||||
|
// If group allowlist is configured, device must be in an allowed group
|
||||||
|
if (groupAllowlist && groupAllowlist.length > 0) {
|
||||||
|
// We'll check this after we have device info
|
||||||
|
return true; // Will be checked in getDevice
|
||||||
|
}
|
||||||
|
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
private _isGroupAllowed(groupId: string): boolean {
|
||||||
|
return !this.config.groupAllowlist || this.config.groupAllowlist.length === 0
|
||||||
|
|| this.config.groupAllowlist.includes(groupId);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Connect to MeshCentral if not already connected.
|
||||||
|
*/
|
||||||
|
private async _ensureConnected(): Promise<void> {
|
||||||
|
if (this.connected) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
const credSummary = this._getCredentialsSummary();
|
||||||
|
|
||||||
|
// Log connection attempt (redacted)
|
||||||
|
this._auditLog(AuditAction.CONNECTION_ATTEMPT, AuditStatus.PENDING, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: `meshcentral://${this.config.meshCentralUrl}`,
|
||||||
|
hasCredentials: credSummary.hasCredentials,
|
||||||
|
hasTotp: credSummary.hasTotp,
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!this.credentials) {
|
||||||
|
this._auditLog(AuditAction.CONNECTION_ATTEMPT, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: `meshcentral://${this.config.meshCentralUrl}`,
|
||||||
|
error: 'Adapter is not configured for authentication',
|
||||||
|
});
|
||||||
|
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Adapter is not configured for authentication',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
this.client = new MeshCtrlClient({
|
||||||
|
url: this.config.meshCentralUrl,
|
||||||
|
timeoutMs: this.config.timeoutMs,
|
||||||
|
});
|
||||||
|
|
||||||
|
try {
|
||||||
|
await this.client.connect(this.credentials);
|
||||||
|
this.connected = true;
|
||||||
|
|
||||||
|
// Log successful connection
|
||||||
|
this._auditLog(AuditAction.CONNECTION_ESTABLISHED, AuditStatus.SUCCESS, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: `meshcentral://${this.config.meshCentralUrl}`,
|
||||||
|
});
|
||||||
|
} catch (error) {
|
||||||
|
this._auditLog(AuditAction.CONNECTION_ATTEMPT, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: `meshcentral://${this.config.meshCentralUrl}`,
|
||||||
|
error: error instanceof Error ? error.message : 'unknown',
|
||||||
|
});
|
||||||
|
|
||||||
|
throw error;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Disconnect from MeshCentral.
|
||||||
|
*/
|
||||||
|
private async _disconnect(): Promise<void> {
|
||||||
|
if (this.connected && this.client) {
|
||||||
|
try {
|
||||||
|
await this.client.disconnect();
|
||||||
|
this._auditLog(AuditAction.CONNECTION_CLOSED, AuditStatus.SUCCESS, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: `meshcentral://${this.config.meshCentralUrl}`,
|
||||||
|
});
|
||||||
|
} finally {
|
||||||
|
this.connected = false;
|
||||||
|
this.client = null;
|
||||||
|
}
|
||||||
|
} else if (this.connected) {
|
||||||
|
this._auditLog(AuditAction.CONNECTION_CLOSED, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: `meshcentral://${this.config.meshCentralUrl}`,
|
||||||
|
error: 'Client was null when attempting disconnect',
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Convert MeshCtrl node response to Device type.
|
||||||
|
*/
|
||||||
|
private _mapNodeToDevice(node: { id: string; name: string; online: boolean; device?: { os?: string; uptime?: number; lastseen?: number; ip?: string[]; agentver?: string } }, group: { id: string; name: string }): Device {
|
||||||
|
const status = node.online ? DeviceStatus.Online : DeviceStatus.Offline;
|
||||||
|
|
||||||
|
return {
|
||||||
|
id: node.id,
|
||||||
|
name: node.name,
|
||||||
|
groupId: group.id,
|
||||||
|
groupName: group.name,
|
||||||
|
status,
|
||||||
|
os: node.device?.os ?? undefined,
|
||||||
|
uptimeSeconds: node.device?.uptime ?? undefined,
|
||||||
|
lastSeen: node.device?.lastseen
|
||||||
|
? new Date(node.device.lastseen * 1000).toISOString()
|
||||||
|
: undefined,
|
||||||
|
ipAddresses: node.device?.ip ?? undefined,
|
||||||
|
agentVersion: node.device?.agentver ?? undefined,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Convert MeshCtrl meshes response to DeviceGroup type.
|
||||||
|
*/
|
||||||
|
private _mapMeshToGroup(mesh: { id: string; name: string; description?: string }): DeviceGroup {
|
||||||
|
return {
|
||||||
|
id: mesh.id,
|
||||||
|
name: mesh.name,
|
||||||
|
description: mesh.description ?? undefined,
|
||||||
|
deviceCount: 0, // Will be populated on demand
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Filter an array by allowlist.
|
||||||
|
*/
|
||||||
|
private _filterByAllowlist<T>(items: T[], getId: (item: T) => string, allowlist?: string[]): T[] {
|
||||||
|
if (!allowlist || allowlist.length === 0) {
|
||||||
|
return items;
|
||||||
|
}
|
||||||
|
|
||||||
|
const allowedIds = new Set(allowlist);
|
||||||
|
return items.filter((item) => allowedIds.has(getId(item)));
|
||||||
|
}
|
||||||
|
|
||||||
|
async listDevices(request?: ListDevicesRequest): Promise<Device[]> {
|
||||||
|
await this._ensureConnected();
|
||||||
|
|
||||||
|
// Log device listing attempt
|
||||||
|
this._auditLog(AuditAction.DEVICE_LISTED, AuditStatus.PENDING, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'all-devices',
|
||||||
|
groupId: request?.groupId,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Get server version first to verify connection
|
||||||
|
try {
|
||||||
|
const versionResponse = await this.client!.sendRequest({
|
||||||
|
action: 'serverversion',
|
||||||
|
});
|
||||||
|
|
||||||
|
if (versionResponse.err) {
|
||||||
|
this._auditLog(AuditAction.MESHCENTRAL_REQUEST, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'serverversion',
|
||||||
|
error: versionResponse.err,
|
||||||
|
});
|
||||||
|
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.MeshCentralError,
|
||||||
|
'Failed to establish connection with MeshCentral server',
|
||||||
|
);
|
||||||
|
} else {
|
||||||
|
this._auditLog(AuditAction.MESHCENTRAL_RESPONSE, AuditStatus.SUCCESS, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'serverversion',
|
||||||
|
});
|
||||||
|
}
|
||||||
|
} catch (error) {
|
||||||
|
await this._disconnect();
|
||||||
|
throw error;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Get meshes (device groups)
|
||||||
|
const meshesResponse = await this.client!.sendRequest({
|
||||||
|
action: 'meshes',
|
||||||
|
});
|
||||||
|
|
||||||
|
if (meshesResponse.err) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.MeshCentralError,
|
||||||
|
'Failed to retrieve device groups from MeshCentral server',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
const meshes = (meshesResponse.meshes ?? []) as Array<{ id: string; name: string }>;
|
||||||
|
|
||||||
|
// If group filter provided, find matching mesh
|
||||||
|
if (request?.groupId) {
|
||||||
|
const targetMesh = meshes.find((m) => m.id === request.groupId);
|
||||||
|
if (!targetMesh) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ResourceNotFound,
|
||||||
|
'Requested device group could not be found',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!this._isGroupAllowed(targetMesh.id)) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ResourceNotFound,
|
||||||
|
'Requested device group could not be found',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return this._getDevicesForMesh(targetMesh);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Get all devices from all meshes
|
||||||
|
const allDevices: Device[] = [];
|
||||||
|
|
||||||
|
for (const mesh of meshes) {
|
||||||
|
const devices = await this._getDevicesForMesh(mesh);
|
||||||
|
allDevices.push(...devices);
|
||||||
|
}
|
||||||
|
|
||||||
|
return allDevices;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Get devices for a specific mesh/group.
|
||||||
|
private async _getDevicesForMesh(mesh: { id: string; name: string }): Promise<Device[]> {
|
||||||
|
const nodesResponse = await this.client!.sendRequest({
|
||||||
|
action: 'nodes',
|
||||||
|
meshid: mesh.id,
|
||||||
|
});
|
||||||
|
|
||||||
|
if (nodesResponse.err) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.MeshCentralError,
|
||||||
|
`Failed to retrieve devices for group: ${mesh.name}`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
const nodes = (nodesResponse.nodes ?? []) as Array<{ id: string; name: string; online: boolean; meshid?: string; device?: { os?: string; uptime?: number; lastseen?: number; ip?: string[]; agentver?: string } }>;
|
||||||
|
|
||||||
|
if (!this._isGroupAllowed(mesh.id)) {
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
|
||||||
|
return nodes
|
||||||
|
.map((node) => this._mapNodeToDevice(node, mesh))
|
||||||
|
.filter((device) => this._isDeviceAllowed(device.id));
|
||||||
|
}
|
||||||
|
|
||||||
|
async getDevice(deviceId: string): Promise<Device> {
|
||||||
|
await this._ensureConnected();
|
||||||
|
|
||||||
|
// Log device access attempt
|
||||||
|
this._auditLog(AuditAction.DEVICE_ACCESS, AuditStatus.PENDING, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: deviceId,
|
||||||
|
});
|
||||||
|
|
||||||
|
// First get all devices to validate allowlist and find the device
|
||||||
|
const allDevices = await this.listDevices();
|
||||||
|
|
||||||
|
const device = allDevices.find((d) => d.id === deviceId);
|
||||||
|
|
||||||
|
if (!device) {
|
||||||
|
this._auditLog(AuditAction.DEVICE_ACCESS, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: deviceId,
|
||||||
|
error: 'Device could not be found',
|
||||||
|
});
|
||||||
|
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ResourceNotFound,
|
||||||
|
'Device could not be found',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check allowlist again after getting device info
|
||||||
|
if (!this._isDeviceAllowed(deviceId)) {
|
||||||
|
this._auditLog(AuditAction.ACCESS_DENIED, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: deviceId,
|
||||||
|
error: 'Device is not authorized for access',
|
||||||
|
});
|
||||||
|
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.AdapterNotFound,
|
||||||
|
'Device is not authorized for access',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
this._auditLog(AuditAction.DEVICE_ACCESS, AuditStatus.SUCCESS, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: deviceId,
|
||||||
|
});
|
||||||
|
|
||||||
|
return device;
|
||||||
|
}
|
||||||
|
|
||||||
|
async listGroups(): Promise<DeviceGroup[]> {
|
||||||
|
await this._ensureConnected();
|
||||||
|
|
||||||
|
const meshesResponse = await this.client!.sendRequest({
|
||||||
|
action: 'meshes',
|
||||||
|
});
|
||||||
|
|
||||||
|
if (meshesResponse.err) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.MeshCentralError,
|
||||||
|
'Failed to retrieve device groups from MeshCentral server',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
const meshes = (meshesResponse.meshes ?? []) as Array<{ id: string; name: string; description?: string }>;
|
||||||
|
|
||||||
|
// Filter by group allowlist if configured
|
||||||
|
const allowedMeshes = this._filterByAllowlist(
|
||||||
|
meshes,
|
||||||
|
(m) => m.id,
|
||||||
|
this.config.groupAllowlist,
|
||||||
|
);
|
||||||
|
|
||||||
|
return allowedMeshes.map((mesh) => this._mapMeshToGroup(mesh));
|
||||||
|
}
|
||||||
|
|
||||||
|
async getGroup(groupId: string): Promise<DeviceGroup> {
|
||||||
|
const groups = await this.listGroups();
|
||||||
|
|
||||||
|
const group = groups.find((g) => g.id === groupId);
|
||||||
|
|
||||||
|
if (!group) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ResourceNotFound,
|
||||||
|
'Device group could not be found',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return group;
|
||||||
|
}
|
||||||
|
|
||||||
|
async runDiagnostic(request: RunDiagnosticRequest): Promise<DiagnosticResult> {
|
||||||
|
const { deviceId, checkType } = request;
|
||||||
|
|
||||||
|
// Log diagnostic attempt
|
||||||
|
this._auditLog(AuditAction.MESHCENTRAL_REQUEST, AuditStatus.PENDING, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: deviceId,
|
||||||
|
checkType,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Validate device is in allowlist
|
||||||
|
if (!this._isDeviceAllowed(deviceId)) {
|
||||||
|
this._auditLog(AuditAction.ACCESS_DENIED, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: deviceId,
|
||||||
|
checkType,
|
||||||
|
error: 'Device is not authorized for access',
|
||||||
|
});
|
||||||
|
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.AdapterNotFound,
|
||||||
|
'Device is not authorized for access',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Get device to verify it exists and get group info
|
||||||
|
await this.getDevice(deviceId);
|
||||||
|
|
||||||
|
// For now, return a placeholder diagnostic result
|
||||||
|
// Real implementation would execute commands via MeshCtrl's deviceinfo or events API
|
||||||
|
const result = {
|
||||||
|
deviceId,
|
||||||
|
checkType,
|
||||||
|
timestamp: new Date().toISOString(),
|
||||||
|
success: true,
|
||||||
|
output: '[Real adapter diagnostic not yet implemented - device is online]',
|
||||||
|
exitCode: 0,
|
||||||
|
outputLength: 49,
|
||||||
|
maxOutputLength: request.maxOutputLength ?? this.config.maxOutputLength,
|
||||||
|
truncated: false,
|
||||||
|
};
|
||||||
|
|
||||||
|
this._auditLog(AuditAction.MESHCENTRAL_RESPONSE, AuditStatus.SUCCESS, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: deviceId,
|
||||||
|
checkType,
|
||||||
|
});
|
||||||
|
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
|
||||||
|
async healthCheck(): Promise<boolean> {
|
||||||
|
// Log health check attempt
|
||||||
|
this._auditLog(AuditAction.SERVICE_START, AuditStatus.PENDING, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'health-check',
|
||||||
|
});
|
||||||
|
|
||||||
|
if (this.config.adapterType !== 'real') {
|
||||||
|
this._auditLog(AuditAction.SERVICE_START, AuditStatus.SUCCESS, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'health-check',
|
||||||
|
adapterType: this.config.adapterType,
|
||||||
|
});
|
||||||
|
return true; // Mock adapter is always healthy
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
await this._ensureConnected();
|
||||||
|
|
||||||
|
const versionResponse = await this.client!.sendRequest({
|
||||||
|
action: 'serverversion',
|
||||||
|
});
|
||||||
|
|
||||||
|
const healthy = !versionResponse.err;
|
||||||
|
this._auditLog(AuditAction.SERVICE_START, healthy ? AuditStatus.SUCCESS : AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'health-check',
|
||||||
|
healthy,
|
||||||
|
});
|
||||||
|
|
||||||
|
return healthy;
|
||||||
|
} catch {
|
||||||
|
this._auditLog(AuditAction.SERVICE_START, AuditStatus.FAILURE, {
|
||||||
|
actor: this._getActorName(),
|
||||||
|
resource: 'health-check',
|
||||||
|
healthy: false,
|
||||||
|
});
|
||||||
|
|
||||||
|
await this._disconnect();
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Cleanup on destroy.
|
||||||
|
*/
|
||||||
|
async destroy(): Promise<void> {
|
||||||
|
await this._disconnect();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Factory function to create the appropriate adapter based on configuration.
|
||||||
|
*/
|
||||||
|
export function createMeshCentralAdapter(config: Partial<BridgeConfig> = {}): MeshCentralAdapter {
|
||||||
|
const adapterType = config.adapterType ?? 'mock';
|
||||||
|
|
||||||
|
switch (adapterType) {
|
||||||
|
case 'real':
|
||||||
|
return new MeshCentralRealAdapter(config);
|
||||||
|
case 'mock':
|
||||||
|
default:
|
||||||
|
return createMockAdapter(config);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,188 @@
|
|||||||
|
/**
|
||||||
|
* Audit logging types and constants.
|
||||||
|
*
|
||||||
|
* Defines the schema for audit log entries and
|
||||||
|
* supported action/status enumerations.
|
||||||
|
*/
|
||||||
|
|
||||||
|
// ========== Audit Actions ==========
|
||||||
|
/**
|
||||||
|
* Enumeration of audit actions tracked by the system.
|
||||||
|
*/
|
||||||
|
export enum AuditAction {
|
||||||
|
// Authentication and authorization
|
||||||
|
AUTH_ATTEMPT = 'AUTH_ATTEMPT',
|
||||||
|
CREDENTIAL_UPDATE = 'CREDENTIAL_UPDATE',
|
||||||
|
|
||||||
|
// Connection events
|
||||||
|
CONNECTION_ATTEMPT = 'CONNECTION_ATTEMPT',
|
||||||
|
CONNECTION_ESTABLISHED = 'CONNECTION_ESTABLISHED',
|
||||||
|
CONNECTION_CLOSED = 'CONNECTION_CLOSED',
|
||||||
|
|
||||||
|
// Configuration
|
||||||
|
CONFIG_LOAD = 'CONFIG_LOAD',
|
||||||
|
CONFIG_CHANGE = 'CONFIG_CHANGE',
|
||||||
|
|
||||||
|
// MeshCentral operations
|
||||||
|
MESHCENTRAL_REQUEST = 'MESHCENTRAL_REQUEST',
|
||||||
|
MESHCENTRAL_RESPONSE = 'MESHCENTRAL_RESPONSE',
|
||||||
|
|
||||||
|
// Device operations
|
||||||
|
DEVICE_LISTED = 'DEVICE_LISTED',
|
||||||
|
DEVICE_ACCESS = 'DEVICE_ACCESS',
|
||||||
|
|
||||||
|
// Group operations
|
||||||
|
GROUP_LISTED = 'GROUP_LISTED',
|
||||||
|
GROUP_ACCESS = 'GROUP_ACCESS',
|
||||||
|
|
||||||
|
// Error events
|
||||||
|
AUTH_FAILURE = 'AUTH_FAILURE',
|
||||||
|
ACCESS_DENIED = 'ACCESS_DENIED',
|
||||||
|
RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
|
||||||
|
|
||||||
|
// Lifecycle
|
||||||
|
SERVICE_START = 'SERVICE_START',
|
||||||
|
SERVICE_STOP = 'SERVICE_STOP',
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Determine if an action is security-critical.
|
||||||
|
*/
|
||||||
|
export function isSecurityAction(action: AuditAction): boolean {
|
||||||
|
const securityActions = [
|
||||||
|
AuditAction.AUTH_ATTEMPT,
|
||||||
|
AuditAction.CREDENTIAL_UPDATE,
|
||||||
|
AuditAction.CONNECTION_ATTEMPT,
|
||||||
|
AuditAction.AUTH_FAILURE,
|
||||||
|
AuditAction.ACCESS_DENIED,
|
||||||
|
];
|
||||||
|
|
||||||
|
return securityActions.includes(action);
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Audit Status ==========
|
||||||
|
/**
|
||||||
|
* Enumeration of audit status values.
|
||||||
|
*/
|
||||||
|
export enum AuditStatus {
|
||||||
|
SUCCESS = 'SUCCESS',
|
||||||
|
FAILURE = 'FAILURE',
|
||||||
|
PENDING = 'PENDING',
|
||||||
|
CANCELLED = 'CANCELLED',
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Audit Log Entry Schema ==========
|
||||||
|
/**
|
||||||
|
* Core audit log entry structure.
|
||||||
|
*
|
||||||
|
* All entries must include these fields to ensure
|
||||||
|
* consistent audit trail quality.
|
||||||
|
*/
|
||||||
|
export interface AuditLogEntry {
|
||||||
|
/**
|
||||||
|
* ISO 8601 timestamp of the event.
|
||||||
|
*/
|
||||||
|
timestamp: string;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The action that was performed.
|
||||||
|
*/
|
||||||
|
action: AuditAction;
|
||||||
|
|
||||||
|
/**
|
||||||
|
*Outcome of the action (SUCCESS, FAILURE, etc.).
|
||||||
|
*/
|
||||||
|
status: AuditStatus;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Actor responsible for the action (username, service name, or 'unknown').
|
||||||
|
*/
|
||||||
|
actor: string;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Resource affected by the action (device ID, group name, etc.).
|
||||||
|
*/
|
||||||
|
resource: string;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Additional context-specific details.
|
||||||
|
* Secrets are already redacted before this object is passed here.
|
||||||
|
*/
|
||||||
|
details?: Record<string, unknown>;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Optional audit log entry for scenarios where some fields may be unavailable.
|
||||||
|
*/
|
||||||
|
export interface OptionalAuditLogEntry extends Omit<AuditLogEntry, 'actor' | 'resource'> {
|
||||||
|
actor?: string;
|
||||||
|
resource?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Validate that a plain object conforms to the AuditLogEntry schema.
|
||||||
|
*/
|
||||||
|
export function isAuditLogEntry(value: unknown): value is AuditLogEntry {
|
||||||
|
if (typeof value !== 'object' || value === null) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
const entry = value as Record<string, unknown>;
|
||||||
|
|
||||||
|
// Check required fields and require a valid ISO-8601 date.
|
||||||
|
if (typeof entry.timestamp !== 'string' || Number.isNaN(Date.parse(entry.timestamp))) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!entry.action || typeof entry.action !== 'string') {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Validate action is a known enum value
|
||||||
|
const validActions = Object.values(AuditAction);
|
||||||
|
if (!validActions.includes(entry.action as AuditAction)) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check status
|
||||||
|
if (!entry.status || typeof entry.status !== 'string') {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
const validStatuses = Object.values(AuditStatus);
|
||||||
|
if (!validStatuses.includes(entry.status as AuditStatus)) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Actor and resource should be strings if present
|
||||||
|
if (entry.actor !== undefined && typeof entry.actor !== 'string') {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (entry.resource !== undefined && typeof entry.resource !== 'string') {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Details, if present, should be an object or undefined
|
||||||
|
if (entry.details !== undefined && typeof entry.details !== 'object') {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Create a partial audit entry with only required fields.
|
||||||
|
*/
|
||||||
|
export function createMinimalAuditEntry(params: {
|
||||||
|
action: AuditAction;
|
||||||
|
status: AuditStatus;
|
||||||
|
}): AuditLogEntry {
|
||||||
|
return {
|
||||||
|
timestamp: new Date().toISOString(),
|
||||||
|
action: params.action,
|
||||||
|
status: params.status,
|
||||||
|
actor: 'unknown',
|
||||||
|
resource: 'unknown',
|
||||||
|
};
|
||||||
|
}
|
||||||
@@ -0,0 +1,150 @@
|
|||||||
|
/**
|
||||||
|
* Structured audit logging with secret redaction.
|
||||||
|
*
|
||||||
|
* Provides typed log entries for security-relevant operations
|
||||||
|
* and utilities to sanitize sensitive data before logging.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { AuditLogEntry, AuditAction, AuditStatus } from './audit-types';
|
||||||
|
|
||||||
|
// ========== Redaction Utilities ==========
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Redact sensitive values from a string or object.
|
||||||
|
* Replaces secrets with "[REDACTED]" while preserving structure.
|
||||||
|
*/
|
||||||
|
export function redactSecrets(value: string | object): string {
|
||||||
|
let text = typeof value === 'string' ? value : JSON.stringify(value);
|
||||||
|
|
||||||
|
// Redact header values for common sensitive headers (before base64/hex)
|
||||||
|
text = text.replace(
|
||||||
|
/("(?:Authorization|X-Auth|Bearer|Token|Secret|Key|x-meshauth)"\s*:\s*)"[^"]*"/gi,
|
||||||
|
'$1"[REDACTED]"',
|
||||||
|
);
|
||||||
|
|
||||||
|
// Redact passwords in known key patterns (before base64/hex)
|
||||||
|
text = text.replace(
|
||||||
|
/("(?:password|secret|token|totp)"\s*:\s*)"[^"]*"/gi,
|
||||||
|
'$1"[REDACTED]"',
|
||||||
|
);
|
||||||
|
|
||||||
|
// Redact hex secrets (32+ chars, hex only) - more specific than base64
|
||||||
|
text = text.replace(
|
||||||
|
/\b([a-fA-F0-9]{32,})\b/g,
|
||||||
|
() => '[REDACTED_HEX]',
|
||||||
|
);
|
||||||
|
|
||||||
|
// Redact base64 credentials (16+ chars including = padding)
|
||||||
|
text = text.replace(
|
||||||
|
/([A-Za-z0-9+/]{16,}={0,2})/g,
|
||||||
|
(match) => {
|
||||||
|
// Only redact if it looks like base64 credentials
|
||||||
|
// Don't double-redact hex strings (which are also valid base64 chars)
|
||||||
|
if (match.length >= 20 && match.length <= 128) {
|
||||||
|
// Check if it's all hex (would have been caught above)
|
||||||
|
if (/^[a-fA-F0-9]+$/.test(match)) {
|
||||||
|
return match; // Let hex redaction handle it
|
||||||
|
}
|
||||||
|
return '[REDACTED_BASE64]';
|
||||||
|
}
|
||||||
|
return match;
|
||||||
|
},
|
||||||
|
);
|
||||||
|
|
||||||
|
return text;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sanitize an object for safe logging by recursively redacting secrets.
|
||||||
|
*/
|
||||||
|
export function sanitizeForLogging<T>(data: T): T {
|
||||||
|
if (typeof data !== 'object' || data === null) {
|
||||||
|
return data;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (Array.isArray(data)) {
|
||||||
|
return data.map((item) => sanitizeForLogging(item)) as T;
|
||||||
|
}
|
||||||
|
|
||||||
|
const sanitized: Record<string, unknown> = {};
|
||||||
|
for (const [key, value] of Object.entries(data)) {
|
||||||
|
const lowerKey = key.toLowerCase();
|
||||||
|
|
||||||
|
// Redact known secret keys
|
||||||
|
if (lowerKey.includes('password') ||
|
||||||
|
lowerKey.includes('secret') ||
|
||||||
|
lowerKey.includes('token') ||
|
||||||
|
lowerKey.includes('auth') ||
|
||||||
|
lowerKey === 'totp' ||
|
||||||
|
lowerKey === 'cred') {
|
||||||
|
sanitized[key] = '[REDACTED]';
|
||||||
|
} else if (typeof value === 'object' && value !== null) {
|
||||||
|
sanitized[key] = sanitizeForLogging(value);
|
||||||
|
} else if (typeof value === 'string') {
|
||||||
|
sanitized[key] = redactSecrets(value);
|
||||||
|
} else {
|
||||||
|
sanitized[key] = value;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return sanitized as T;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Audit Log Entry Utilities ==========
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Create a new audit log entry with required fields.
|
||||||
|
*/
|
||||||
|
export function createAuditEntry(params: {
|
||||||
|
action: AuditAction;
|
||||||
|
status: AuditStatus;
|
||||||
|
actor?: string;
|
||||||
|
resource?: string;
|
||||||
|
details?: Record<string, unknown>;
|
||||||
|
}): AuditLogEntry {
|
||||||
|
const { action, status, actor, resource, details } = params;
|
||||||
|
|
||||||
|
// Redact any secrets in details
|
||||||
|
const sanitizedDetails = details ? sanitizeForLogging(details) : undefined;
|
||||||
|
|
||||||
|
return {
|
||||||
|
timestamp: new Date().toISOString(),
|
||||||
|
action,
|
||||||
|
status,
|
||||||
|
actor: actor ?? 'unknown',
|
||||||
|
resource: resource ?? 'unknown',
|
||||||
|
details: sanitizedDetails,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Format an audit log entry as a JSON string for output.
|
||||||
|
*/
|
||||||
|
export function formatAuditEntry(entry: AuditLogEntry): string {
|
||||||
|
return JSON.stringify(entry, null, 2);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if an audit action is security-critical.
|
||||||
|
*/
|
||||||
|
export function isSecurityCritical(action: AuditAction): boolean {
|
||||||
|
const securityActions: AuditAction[] = [
|
||||||
|
AuditAction.AUTH_ATTEMPT,
|
||||||
|
AuditAction.CREDENTIAL_UPDATE,
|
||||||
|
AuditAction.DEVICE_ACCESS,
|
||||||
|
AuditAction.GROUP_ACCESS,
|
||||||
|
AuditAction.ACCESS_DENIED,
|
||||||
|
AuditAction.CONFIG_CHANGE,
|
||||||
|
AuditAction.CONNECTION_ATTEMPT,
|
||||||
|
];
|
||||||
|
|
||||||
|
return securityActions.includes(action);
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Export Types ==========
|
||||||
|
|
||||||
|
export {
|
||||||
|
AuditLogEntry,
|
||||||
|
AuditAction,
|
||||||
|
AuditStatus,
|
||||||
|
};
|
||||||
@@ -0,0 +1,263 @@
|
|||||||
|
/**
|
||||||
|
* Typed contracts for MeshCentral ↔ OpenClaw Bridge
|
||||||
|
*
|
||||||
|
* Defines the interface between the bridge and OpenClaw.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { z } from 'zod';
|
||||||
|
|
||||||
|
// ========== Credential Validation Schemas ==========
|
||||||
|
/**
|
||||||
|
* Validate username: alphanumeric, hyphens, underscores only, 1-64 chars
|
||||||
|
*/
|
||||||
|
export const UsernameSchema = z.string()
|
||||||
|
.min(1, 'Username is required')
|
||||||
|
.max(64, 'Username must be 64 characters or less')
|
||||||
|
.regex(/^[a-zA-Z0-9_-]+$/, 'Username must contain only alphanumeric characters, hyphens, and underscores');
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Validate password: 8-128 chars, any printable characters except colons
|
||||||
|
*/
|
||||||
|
export const PasswordSchema = z.string()
|
||||||
|
.min(8, 'Password must be at least 8 characters')
|
||||||
|
.max(128, 'Password must be 128 characters or less');
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Validate TOTP token: 6-8 digits only
|
||||||
|
*/
|
||||||
|
export const TotpSchema = z.string()
|
||||||
|
.optional()
|
||||||
|
.refine((val) => val === undefined || /^[0-9]{6,8}$/.test(val), {
|
||||||
|
message: 'TOTP token must be 6-8 digits',
|
||||||
|
});
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sanitize credentials for safe logging.
|
||||||
|
* Returns a redacted object without exposing actual values.
|
||||||
|
*/
|
||||||
|
export function sanitizeCredentials(credentials?: {
|
||||||
|
username?: string;
|
||||||
|
password?: string;
|
||||||
|
totpToken?: string;
|
||||||
|
}): { hasCredentials: boolean; redacted: true } {
|
||||||
|
if (!credentials) {
|
||||||
|
return { hasCredentials: false, redacted: true };
|
||||||
|
}
|
||||||
|
|
||||||
|
const { username, password } = credentials;
|
||||||
|
|
||||||
|
// Return redacted representation - never log actual values
|
||||||
|
return {
|
||||||
|
hasCredentials: !!username && !!password,
|
||||||
|
redacted: true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Validate credentials structure without exposing values in errors.
|
||||||
|
* Generic error messages prevent credential enumeration attacks.
|
||||||
|
*/
|
||||||
|
export function validateCredentials(credentials: {
|
||||||
|
username?: string;
|
||||||
|
password?: string;
|
||||||
|
totpToken?: string;
|
||||||
|
}): void {
|
||||||
|
const hasUsername = !!credentials.username;
|
||||||
|
const hasPassword = !!credentials.password;
|
||||||
|
|
||||||
|
// Generic error message that doesn't reveal which credential is missing
|
||||||
|
if (hasUsername !== hasPassword) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Authentication configuration is incomplete',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (hasUsername && hasPassword) {
|
||||||
|
// Validate format only, don't log values
|
||||||
|
try {
|
||||||
|
UsernameSchema.parse(credentials.username);
|
||||||
|
} catch {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Invalid authentication credentials',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
PasswordSchema.parse(credentials.password);
|
||||||
|
} catch {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Invalid authentication credentials',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Device Status ==========
|
||||||
|
export enum DeviceStatus {
|
||||||
|
Online = 'online',
|
||||||
|
Offline = 'offline',
|
||||||
|
Unknown = 'unknown',
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Device Schema ==========
|
||||||
|
export const DeviceSchema = z.object({
|
||||||
|
id: z.string(),
|
||||||
|
name: z.string(),
|
||||||
|
groupId: z.string(),
|
||||||
|
groupName: z.string(),
|
||||||
|
status: z.nativeEnum(DeviceStatus),
|
||||||
|
os: z.string().optional(),
|
||||||
|
uptimeSeconds: z.number().optional(),
|
||||||
|
lastSeen: z.string().datetime().optional(),
|
||||||
|
ipAddresses: z.array(z.string()).optional(),
|
||||||
|
agentVersion: z.string().optional(),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type Device = z.infer<typeof DeviceSchema>;
|
||||||
|
|
||||||
|
// ========== Device Group Schema ==========
|
||||||
|
export const DeviceGroupSchema = z.object({
|
||||||
|
id: z.string(),
|
||||||
|
name: z.string(),
|
||||||
|
description: z.string().optional(),
|
||||||
|
deviceCount: z.number(),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type DeviceGroup = z.infer<typeof DeviceGroupSchema>;
|
||||||
|
|
||||||
|
// ========== Diagnostic Check Types ==========
|
||||||
|
export enum DiagnosticCheckType {
|
||||||
|
DiskSpace = 'diskSpace',
|
||||||
|
Services = 'services',
|
||||||
|
Processes = 'processes',
|
||||||
|
OSDetails = 'osDetails',
|
||||||
|
NetworkState = 'networkState',
|
||||||
|
Uptime = 'uptime',
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Diagnostic Result Schema ==========
|
||||||
|
export const DiagnosticResultSchema = z.object({
|
||||||
|
deviceId: z.string(),
|
||||||
|
checkType: z.nativeEnum(DiagnosticCheckType),
|
||||||
|
timestamp: z.string().datetime(),
|
||||||
|
success: z.boolean(),
|
||||||
|
output: z.string(),
|
||||||
|
exitCode: z.number().nullable(),
|
||||||
|
truncated: z.boolean().optional(),
|
||||||
|
outputLength: z.number(),
|
||||||
|
maxOutputLength: z.number().optional(),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type DiagnosticResult = z.infer<typeof DiagnosticResultSchema>;
|
||||||
|
|
||||||
|
// ========== Error Handling ==========
|
||||||
|
export enum ErrorCodes {
|
||||||
|
// Bridge errors
|
||||||
|
AdapterNotFound = 'ADAPTER_NOT_FOUND',
|
||||||
|
ConfigurationInvalid = 'CONFIGURATION_INVALID',
|
||||||
|
TimeoutExceeded = 'TIMEOUT_EXCEEDED',
|
||||||
|
OutputLimitExceeded = 'OUTPUT_LIMIT_EXCEEDED',
|
||||||
|
|
||||||
|
// Adapter communication errors
|
||||||
|
AuthenticationFailed = 'AUTHENTICATION_FAILED',
|
||||||
|
ConnectionFailed = 'CONNECTION_FAILED',
|
||||||
|
ResourceNotFound = 'RESOURCE_NOT_FOUND',
|
||||||
|
|
||||||
|
// MeshCentral-specific errors
|
||||||
|
MeshCentralError = 'MESHCENTRAL_ERROR',
|
||||||
|
}
|
||||||
|
|
||||||
|
export class BridgeError extends Error {
|
||||||
|
constructor(
|
||||||
|
public code: ErrorCodes,
|
||||||
|
message: string,
|
||||||
|
public details?: unknown,
|
||||||
|
) {
|
||||||
|
super(message);
|
||||||
|
this.name = 'BridgeError';
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export const BridgeErrorResponseSchema = z.object({
|
||||||
|
error: z.object({
|
||||||
|
code: z.string(),
|
||||||
|
message: z.string(),
|
||||||
|
details: z.unknown().optional(),
|
||||||
|
}),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type BridgeErrorResponse = z.infer<typeof BridgeErrorResponseSchema>;
|
||||||
|
|
||||||
|
// ========== Request/Response Contracts ==========
|
||||||
|
export const ListDevicesRequestSchema = z.object({
|
||||||
|
groupId: z.string().optional(),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type ListDevicesRequest = z.infer<typeof ListDevicesRequestSchema>;
|
||||||
|
|
||||||
|
export const GetDeviceDetailsRequestSchema = z.object({
|
||||||
|
deviceId: z.string(),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type GetDeviceDetailsRequest = z.infer<
|
||||||
|
typeof GetDeviceDetailsRequestSchema
|
||||||
|
>;
|
||||||
|
|
||||||
|
export const RunDiagnosticRequestSchema = z.object({
|
||||||
|
deviceId: z.string(),
|
||||||
|
checkType: z.nativeEnum(DiagnosticCheckType),
|
||||||
|
timeoutMs: z.number().optional(),
|
||||||
|
maxOutputLength: z.number().optional(),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type RunDiagnosticRequest = z.infer<
|
||||||
|
typeof RunDiagnosticRequestSchema
|
||||||
|
>;
|
||||||
|
|
||||||
|
// ========== Adapter Interface ==========
|
||||||
|
export interface MeshCentralAdapter {
|
||||||
|
readonly name: string;
|
||||||
|
readonly version: string;
|
||||||
|
|
||||||
|
// Device listing
|
||||||
|
listDevices(request?: ListDevicesRequest): Promise<Device[]>;
|
||||||
|
getDevice(deviceId: string): Promise<Device>;
|
||||||
|
|
||||||
|
// Device groups
|
||||||
|
listGroups(): Promise<DeviceGroup[]>;
|
||||||
|
getGroup(groupId: string): Promise<DeviceGroup>;
|
||||||
|
|
||||||
|
// Diagnostics (read-only)
|
||||||
|
runDiagnostic(request: RunDiagnosticRequest): Promise<DiagnosticResult>;
|
||||||
|
|
||||||
|
// Health check
|
||||||
|
healthCheck(): Promise<boolean>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Mock Configuration ==========
|
||||||
|
export interface BridgeConfig {
|
||||||
|
meshCentralUrl: string;
|
||||||
|
adapterType: 'real' | 'mock';
|
||||||
|
timeoutMs: number;
|
||||||
|
maxOutputLength: number;
|
||||||
|
|
||||||
|
// Security: Allowlist for PVE3 and specific devices
|
||||||
|
pveAllowlist?: string[]; // PVE node IDs (e.g., ['pve3'])
|
||||||
|
deviceAllowlist?: string[]; // Device IDs (e.g., ['dev-001', 'dev-002'])
|
||||||
|
groupAllowlist?: string[]; // Group IDs (e.g., ['grp-servers'])
|
||||||
|
|
||||||
|
// Authentication (never logged, set at runtime)
|
||||||
|
username?: string;
|
||||||
|
password?: string;
|
||||||
|
totpToken?: string; // Optional 2FA token
|
||||||
|
}
|
||||||
|
|
||||||
|
export const defaultConfig: BridgeConfig = {
|
||||||
|
meshCentralUrl: 'http://localhost:8080',
|
||||||
|
adapterType: 'mock',
|
||||||
|
timeoutMs: 10_000,
|
||||||
|
maxOutputLength: 65_536, // 64 KB
|
||||||
|
};
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
/**
|
||||||
|
* MeshCentral ↔ OpenClaw Bridge
|
||||||
|
*
|
||||||
|
* Read-only integration for device inventory and diagnostics.
|
||||||
|
*/
|
||||||
|
|
||||||
|
export { createMeshCentralAdapter } from './adapter';
|
||||||
|
export {
|
||||||
|
Device,
|
||||||
|
DeviceGroup,
|
||||||
|
DeviceStatus,
|
||||||
|
DiagnosticResult,
|
||||||
|
DiagnosticCheckType,
|
||||||
|
ErrorCodes,
|
||||||
|
BridgeError,
|
||||||
|
MeshCentralAdapter,
|
||||||
|
BridgeConfig,
|
||||||
|
} from './contracts';
|
||||||
|
export { createMockAdapter } from './mock-adapter';
|
||||||
|
|
||||||
|
// Protocol client exports
|
||||||
|
export {
|
||||||
|
MeshCtrlClient,
|
||||||
|
encodeAuthHeader,
|
||||||
|
createRequest,
|
||||||
|
parseResponse,
|
||||||
|
validateResponseForAction,
|
||||||
|
isErrorResponse,
|
||||||
|
getErrorResponseMessage,
|
||||||
|
CONTROL_PATH,
|
||||||
|
} from './meshctrl-client';
|
||||||
|
|
||||||
|
// Audit logging exports
|
||||||
|
export {
|
||||||
|
createAuditEntry,
|
||||||
|
sanitizeForLogging,
|
||||||
|
redactSecrets,
|
||||||
|
isSecurityCritical,
|
||||||
|
AuditAction,
|
||||||
|
AuditStatus,
|
||||||
|
AuditLogEntry,
|
||||||
|
} from './audit';
|
||||||
|
|
||||||
|
// Structured logger exports
|
||||||
|
export {
|
||||||
|
Logger,
|
||||||
|
ConsoleLogger,
|
||||||
|
LogLevel,
|
||||||
|
createLogger,
|
||||||
|
getGlobalLogger,
|
||||||
|
setGlobalLogger,
|
||||||
|
resetGlobalLogger,
|
||||||
|
redactSecrets as redact,
|
||||||
|
sanitizeForLogging as sanitize,
|
||||||
|
} from './logger';
|
||||||
@@ -0,0 +1,97 @@
|
|||||||
|
/**
|
||||||
|
* Narrow MeshCentral compatibility probe.
|
||||||
|
*
|
||||||
|
* This file intentionally has no CLI credential or target arguments. The
|
||||||
|
* password is read at runtime from the protected credential file and is never
|
||||||
|
* printed. Only serverversion, meshes, and nodes requests are sent.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { readFileSync, statSync } from 'node:fs';
|
||||||
|
import { MeshCtrlAction, MeshCtrlClient } from './meshctrl-client';
|
||||||
|
|
||||||
|
/* eslint-disable no-console -- CLI probe intentionally emits one safe result or generic failure. */
|
||||||
|
|
||||||
|
const DEFAULT_CREDENTIAL_FILE = '/home/ledadmin/.openclaw/workspace/Credentials/.meshcentral-credentials';
|
||||||
|
const MESH_URL = 'https://mesh.ledrew.me';
|
||||||
|
const USERNAME = 'sa_clawdia';
|
||||||
|
const APPROVED_GROUP_NAME = 'Servers';
|
||||||
|
const APPROVED_DEVICE_NAME = 'PVE3';
|
||||||
|
|
||||||
|
function readProtectedPassword(filePath = DEFAULT_CREDENTIAL_FILE): string {
|
||||||
|
const mode = statSync(filePath).mode & 0o777;
|
||||||
|
if (mode !== 0o600) {
|
||||||
|
throw new Error('Credential file permissions must be exactly 0600');
|
||||||
|
}
|
||||||
|
const password = readFileSync(filePath, 'utf8').trim();
|
||||||
|
if (!password) {
|
||||||
|
throw new Error('Credential file is empty');
|
||||||
|
}
|
||||||
|
return password;
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function runReadOnlyCompatibilityTest(): Promise<void> {
|
||||||
|
const password = readProtectedPassword();
|
||||||
|
const client = new MeshCtrlClient({ url: MESH_URL, timeoutMs: 30_000 });
|
||||||
|
let stage = 'connect';
|
||||||
|
|
||||||
|
try {
|
||||||
|
await client.connect({ username: USERNAME, password });
|
||||||
|
stage = 'serverversion';
|
||||||
|
const version = await client.sendRequest({ action: MeshCtrlAction.ServerVersion });
|
||||||
|
stage = 'meshes';
|
||||||
|
const meshesResponse = await client.sendRequest({ action: MeshCtrlAction.Meshes });
|
||||||
|
const meshes = Array.isArray(meshesResponse.meshes) ? meshesResponse.meshes as Array<{ id: string; name: string }> : [];
|
||||||
|
const approvedGroup = meshes.find((mesh) => mesh.name === APPROVED_GROUP_NAME);
|
||||||
|
|
||||||
|
if (!approvedGroup) {
|
||||||
|
throw new Error('Approved MeshCentral group was not found');
|
||||||
|
}
|
||||||
|
|
||||||
|
stage = 'nodes';
|
||||||
|
const nodesResponse = await client.sendRequest({
|
||||||
|
action: MeshCtrlAction.Nodes,
|
||||||
|
meshid: approvedGroup.id,
|
||||||
|
});
|
||||||
|
const nodes = Array.isArray(nodesResponse.nodes) ? nodesResponse.nodes as Array<{ id: string; name: string; meshid: string; online: boolean }> : [];
|
||||||
|
const approvedDevice = nodes.find((node) => node.name === APPROVED_DEVICE_NAME);
|
||||||
|
|
||||||
|
if (!approvedDevice) {
|
||||||
|
throw new Error('Approved PVE3 device was not found in the Servers group');
|
||||||
|
}
|
||||||
|
|
||||||
|
stage = 'deviceinfo';
|
||||||
|
const deviceInfo = await client.sendRequest({
|
||||||
|
action: MeshCtrlAction.DeviceInfo,
|
||||||
|
nodeid: approvedDevice.id,
|
||||||
|
});
|
||||||
|
if (deviceInfo.err || !deviceInfo.device) {
|
||||||
|
throw new Error('Approved PVE3 metadata could not be retrieved');
|
||||||
|
}
|
||||||
|
|
||||||
|
// Deliberately emit only non-sensitive compatibility facts.
|
||||||
|
console.log(JSON.stringify({
|
||||||
|
success: true,
|
||||||
|
serverVersionAction: version.action,
|
||||||
|
serverVersionResult: typeof version.result === 'string' ? version.result : undefined,
|
||||||
|
group: APPROVED_GROUP_NAME,
|
||||||
|
device: { name: approvedDevice.name, online: approvedDevice.online },
|
||||||
|
}));
|
||||||
|
} catch (error: unknown) {
|
||||||
|
const message = error instanceof Error ? error.message : '';
|
||||||
|
const category = message.includes('timed out') ? 'timeout' : 'protocol-or-connection';
|
||||||
|
throw new Error(`live test failed at ${stage} (${category})`);
|
||||||
|
} finally {
|
||||||
|
await client.disconnect();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (require.main === module) {
|
||||||
|
runReadOnlyCompatibilityTest().catch((error: unknown) => {
|
||||||
|
// Report only a generic error class and stage; never server text.
|
||||||
|
const message = error instanceof Error ? error.message : '';
|
||||||
|
const safeMessage = /^live test failed at (connect|serverversion|meshes|nodes|deviceinfo) \((timeout|protocol-or-connection)\)$/.exec(message)?.[0]
|
||||||
|
?? 'Read-only MeshCentral compatibility test failed';
|
||||||
|
console.error(safeMessage);
|
||||||
|
process.exitCode = 1;
|
||||||
|
});
|
||||||
|
}
|
||||||
@@ -0,0 +1,308 @@
|
|||||||
|
/**
|
||||||
|
* Structured logger with redaction utilities.
|
||||||
|
*
|
||||||
|
* Provides a minimal, structured logging abstraction with
|
||||||
|
* log levels and automatic secret redaction for safe output.
|
||||||
|
*/
|
||||||
|
|
||||||
|
// ========== Log Levels ==========
|
||||||
|
/**
|
||||||
|
* Log severity levels in order of increasing verbosity.
|
||||||
|
*/
|
||||||
|
export enum LogLevel {
|
||||||
|
Audit = 'audit',
|
||||||
|
Error = 'error',
|
||||||
|
Warn = 'warn',
|
||||||
|
Info = 'info',
|
||||||
|
Debug = 'debug',
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if a log level is enabled (for filtering).
|
||||||
|
*/
|
||||||
|
export function isLevelEnabled(level: LogLevel, minLevel: LogLevel): boolean {
|
||||||
|
const order = [
|
||||||
|
LogLevel.Audit,
|
||||||
|
LogLevel.Error,
|
||||||
|
LogLevel.Warn,
|
||||||
|
LogLevel.Info,
|
||||||
|
LogLevel.Debug,
|
||||||
|
];
|
||||||
|
return order.indexOf(level) >= order.indexOf(minLevel);
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Redaction Utilities ==========
|
||||||
|
/**
|
||||||
|
* Redact sensitive values from a string or object.
|
||||||
|
* Replaces secrets with "[REDACTED]" while preserving structure.
|
||||||
|
*/
|
||||||
|
export function redactSecrets(value: string | object): string {
|
||||||
|
let text = typeof value === 'string' ? value : JSON.stringify(value);
|
||||||
|
|
||||||
|
// Redact header values for common sensitive headers (before base64/hex)
|
||||||
|
text = text.replace(
|
||||||
|
/("(?:Authorization|X-Auth|Bearer|Token|Secret|Key|x-meshauth)"\s*:\s*)"[^"]*"/gi,
|
||||||
|
'$1"[REDACTED]"',
|
||||||
|
);
|
||||||
|
|
||||||
|
// Redact passwords in known key patterns (before base64/hex)
|
||||||
|
text = text.replace(
|
||||||
|
/("(?:password|secret|token|totp)"\s*:\s*)"[^"]*"/gi,
|
||||||
|
'$1"[REDACTED]"',
|
||||||
|
);
|
||||||
|
|
||||||
|
// Redact hex secrets (32+ chars, hex only) - more specific than base64
|
||||||
|
text = text.replace(
|
||||||
|
/\b([a-fA-F0-9]{32,})\b/g,
|
||||||
|
() => '[REDACTED_HEX]',
|
||||||
|
);
|
||||||
|
|
||||||
|
// Redact base64 credentials (16+ chars including = padding)
|
||||||
|
text = text.replace(
|
||||||
|
/([A-Za-z0-9+/]{16,}={0,2})/g,
|
||||||
|
(match) => {
|
||||||
|
// Only redact if it looks like base64 credentials
|
||||||
|
// Don't double-redact hex strings (which are also valid base64 chars)
|
||||||
|
if (match.length >= 20 && match.length <= 128) {
|
||||||
|
// Check if it's all hex (would have been caught above)
|
||||||
|
if (/^[a-fA-F0-9]+$/.test(match)) {
|
||||||
|
return match; // Let hex redaction handle it
|
||||||
|
}
|
||||||
|
return '[REDACTED_BASE64]';
|
||||||
|
}
|
||||||
|
return match;
|
||||||
|
},
|
||||||
|
);
|
||||||
|
|
||||||
|
return text;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sanitize an object for safe logging by recursively redacting secrets.
|
||||||
|
*/
|
||||||
|
export function sanitizeForLogging<T>(data: T): T {
|
||||||
|
if (typeof data !== 'object' || data === null) {
|
||||||
|
return data;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (Array.isArray(data)) {
|
||||||
|
return data.map((item) => sanitizeForLogging(item)) as T;
|
||||||
|
}
|
||||||
|
|
||||||
|
const sanitized: Record<string, unknown> = {};
|
||||||
|
for (const [key, value] of Object.entries(data)) {
|
||||||
|
const lowerKey = key.toLowerCase();
|
||||||
|
|
||||||
|
// Redact known secret keys
|
||||||
|
if (lowerKey.includes('password') ||
|
||||||
|
lowerKey.includes('secret') ||
|
||||||
|
lowerKey.includes('token') ||
|
||||||
|
lowerKey.includes('auth') ||
|
||||||
|
lowerKey === 'totp' ||
|
||||||
|
lowerKey === 'cred') {
|
||||||
|
sanitized[key] = '[REDACTED]';
|
||||||
|
} else if (typeof value === 'object' && value !== null) {
|
||||||
|
sanitized[key] = sanitizeForLogging(value);
|
||||||
|
} else if (typeof value === 'string') {
|
||||||
|
sanitized[key] = redactSecrets(value);
|
||||||
|
} else {
|
||||||
|
sanitized[key] = value;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return sanitized as T;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Log Entry ==========
|
||||||
|
/**
|
||||||
|
* A structured log entry.
|
||||||
|
*/
|
||||||
|
export interface LogEntry {
|
||||||
|
timestamp: string;
|
||||||
|
level: LogLevel;
|
||||||
|
message: string;
|
||||||
|
context?: Record<string, unknown>;
|
||||||
|
error?: Error | string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Format a log entry for output.
|
||||||
|
*/
|
||||||
|
export function formatLogEntry(entry: LogEntry): string {
|
||||||
|
const timestamp = entry.timestamp;
|
||||||
|
const level = entry.level.toUpperCase().padEnd(5);
|
||||||
|
let output = `[${timestamp}] ${level} ${entry.message}`;
|
||||||
|
|
||||||
|
if (entry.context && Object.keys(entry.context).length > 0) {
|
||||||
|
const contextStr = JSON.stringify(sanitizeForLogging(entry.context));
|
||||||
|
output += ` ${contextStr}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (entry.error) {
|
||||||
|
const errorStr = entry.error instanceof Error
|
||||||
|
? entry.error.message
|
||||||
|
: String(entry.error);
|
||||||
|
output += ` [error: ${redactSecrets(errorStr)}]`;
|
||||||
|
}
|
||||||
|
|
||||||
|
return output;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Logger Interface ==========
|
||||||
|
/**
|
||||||
|
* Core logger interface with log levels.
|
||||||
|
*/
|
||||||
|
export interface Logger {
|
||||||
|
audit(message: string, context?: Record<string, unknown>): void;
|
||||||
|
debug(message: string, context?: Record<string, unknown>): void;
|
||||||
|
info(message: string, context?: Record<string, unknown>): void;
|
||||||
|
warn(message: string, context?: Record<string, unknown>): void;
|
||||||
|
error(message: string, contextOrError?: Record<string, unknown> | Error): void;
|
||||||
|
|
||||||
|
// Methods to configure the logger
|
||||||
|
setLevel(level: LogLevel): void;
|
||||||
|
getLevel(): LogLevel;
|
||||||
|
setName(name: string): void;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Default Logger Implementation ==========
|
||||||
|
/**
|
||||||
|
* Default logger implementation with console output.
|
||||||
|
*/
|
||||||
|
export class ConsoleLogger implements Logger {
|
||||||
|
private level: LogLevel;
|
||||||
|
private name: string;
|
||||||
|
|
||||||
|
constructor(options?: { level?: LogLevel; name?: string }) {
|
||||||
|
this.level = options?.level ?? LogLevel.Info;
|
||||||
|
this.name = options?.name ?? 'app';
|
||||||
|
}
|
||||||
|
|
||||||
|
debug(message: string, context?: Record<string, unknown>): void {
|
||||||
|
if (isLevelEnabled(LogLevel.Debug, this.level)) {
|
||||||
|
this._log(LogLevel.Debug, message, context);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
info(message: string, context?: Record<string, unknown>): void {
|
||||||
|
if (isLevelEnabled(LogLevel.Info, this.level)) {
|
||||||
|
this._log(LogLevel.Info, message, context);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
warn(message: string, context?: Record<string, unknown>): void {
|
||||||
|
if (isLevelEnabled(LogLevel.Warn, this.level)) {
|
||||||
|
this._log(LogLevel.Warn, message, context);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
error(message: string, contextOrError?: Record<string, unknown> | Error): void {
|
||||||
|
if (isLevelEnabled(LogLevel.Error, this.level)) {
|
||||||
|
const context = (contextOrError instanceof Error || typeof contextOrError !== 'object')
|
||||||
|
? undefined
|
||||||
|
: contextOrError;
|
||||||
|
const error = (contextOrError instanceof Error || typeof contextOrError === 'string')
|
||||||
|
? contextOrError
|
||||||
|
: undefined;
|
||||||
|
this._log(LogLevel.Error, message, context, error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
setLevel(level: LogLevel): void {
|
||||||
|
this.level = level;
|
||||||
|
}
|
||||||
|
|
||||||
|
getLevel(): LogLevel {
|
||||||
|
return this.level;
|
||||||
|
}
|
||||||
|
|
||||||
|
setName(name: string): void {
|
||||||
|
this.name = name;
|
||||||
|
}
|
||||||
|
|
||||||
|
audit(message: string, context?: Record<string, unknown>): void {
|
||||||
|
if (isLevelEnabled(LogLevel.Audit, this.level)) {
|
||||||
|
this._log(LogLevel.Audit, message, context);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private _log(
|
||||||
|
level: LogLevel,
|
||||||
|
message: string,
|
||||||
|
context?: Record<string, unknown>,
|
||||||
|
error?: Error | string,
|
||||||
|
): void {
|
||||||
|
const entry: LogEntry = {
|
||||||
|
timestamp: new Date().toISOString(),
|
||||||
|
level,
|
||||||
|
message: `[${this.name}] ${message}`,
|
||||||
|
context: context ? sanitizeForLogging(context) : undefined,
|
||||||
|
error,
|
||||||
|
};
|
||||||
|
|
||||||
|
const output = formatLogEntry(entry);
|
||||||
|
|
||||||
|
switch (level) {
|
||||||
|
case LogLevel.Audit:
|
||||||
|
// eslint-disable-next-line no-console
|
||||||
|
console.log(output);
|
||||||
|
break;
|
||||||
|
case LogLevel.Debug:
|
||||||
|
// eslint-disable-next-line no-console
|
||||||
|
console.debug(output);
|
||||||
|
break;
|
||||||
|
case LogLevel.Info:
|
||||||
|
// eslint-disable-next-line no-console
|
||||||
|
console.info(output);
|
||||||
|
break;
|
||||||
|
case LogLevel.Warn:
|
||||||
|
// eslint-disable-next-line no-console
|
||||||
|
console.warn(output);
|
||||||
|
break;
|
||||||
|
case LogLevel.Error:
|
||||||
|
// eslint-disable-next-line no-console
|
||||||
|
console.error(output);
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Factory Functions ==========
|
||||||
|
/**
|
||||||
|
* Create a new logger instance.
|
||||||
|
*/
|
||||||
|
export function createLogger(options?: { level?: LogLevel; name?: string }): Logger {
|
||||||
|
return new ConsoleLogger(options);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Global logger instance (singleton pattern).
|
||||||
|
*/
|
||||||
|
let _globalLogger: Logger | null = null;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get or create the global logger.
|
||||||
|
*/
|
||||||
|
export function getGlobalLogger(): Logger {
|
||||||
|
if (!_globalLogger) {
|
||||||
|
_globalLogger = createLogger({
|
||||||
|
level: (process.env.LOG_LEVEL as LogLevel) ?? LogLevel.Info,
|
||||||
|
name: process.env.LOG_NAME ?? 'bridge',
|
||||||
|
});
|
||||||
|
}
|
||||||
|
return _globalLogger;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Set the global logger instance.
|
||||||
|
*/
|
||||||
|
export function setGlobalLogger(logger: Logger): void {
|
||||||
|
_globalLogger = logger;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reset the global logger (useful for testing).
|
||||||
|
*/
|
||||||
|
export function resetGlobalLogger(): void {
|
||||||
|
_globalLogger = null;
|
||||||
|
}
|
||||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,226 @@
|
|||||||
|
/**
|
||||||
|
* Mock adapter for development and testing.
|
||||||
|
*
|
||||||
|
* Simulates MeshCentral device data without actual connectivity.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import {
|
||||||
|
MeshCentralAdapter,
|
||||||
|
Device,
|
||||||
|
DeviceGroup,
|
||||||
|
DeviceStatus,
|
||||||
|
DiagnosticResult,
|
||||||
|
DiagnosticCheckType,
|
||||||
|
BridgeError,
|
||||||
|
ErrorCodes,
|
||||||
|
ListDevicesRequest,
|
||||||
|
RunDiagnosticRequest,
|
||||||
|
defaultConfig,
|
||||||
|
} from './contracts';
|
||||||
|
|
||||||
|
const MOCK_DEVICES: Device[] = [
|
||||||
|
{
|
||||||
|
id: 'dev-001',
|
||||||
|
name: 'home-server',
|
||||||
|
groupId: 'grp-servers',
|
||||||
|
groupName: 'Servers',
|
||||||
|
status: DeviceStatus.Online,
|
||||||
|
os: 'Ubuntu 24.04 LTS',
|
||||||
|
uptimeSeconds: 86400 * 15, // 15 days
|
||||||
|
lastSeen: new Date(Date.now() - 60_000).toISOString(),
|
||||||
|
ipAddresses: ['192.168.1.10', 'fd00::1'],
|
||||||
|
agentVersion: '2.4.1',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: 'dev-002',
|
||||||
|
name: 'proxmox-prod',
|
||||||
|
groupId: 'grp-servers',
|
||||||
|
groupName: 'Servers',
|
||||||
|
status: DeviceStatus.Online,
|
||||||
|
os: 'Proxmox VE 8.2',
|
||||||
|
uptimeSeconds: 86400 * 3, // 3 days
|
||||||
|
lastSeen: new Date(Date.now() - 120_000).toISOString(),
|
||||||
|
ipAddresses: ['192.168.1.13', 'fd00::2'],
|
||||||
|
agentVersion: '2.4.1',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: 'dev-003',
|
||||||
|
name: 'test-lab-client',
|
||||||
|
groupId: 'grp-workstations',
|
||||||
|
groupName: 'Workstations',
|
||||||
|
status: DeviceStatus.Offline,
|
||||||
|
os: 'Windows 11 Pro',
|
||||||
|
uptimeSeconds: null as unknown as number, // Not available when offline
|
||||||
|
lastSeen: new Date(Date.now() - 86400_000).toISOString(), // 1 day ago
|
||||||
|
ipAddresses: ['192.168.1.50'],
|
||||||
|
agentVersion: '2.4.1',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: 'dev-004',
|
||||||
|
name: 'raspberry-pi-01',
|
||||||
|
groupId: 'grp-devices',
|
||||||
|
groupName: 'IoT Devices',
|
||||||
|
status: DeviceStatus.Online,
|
||||||
|
os: 'Raspberry Pi OS 12 (Bookworm)',
|
||||||
|
uptimeSeconds: 86400 * 7, // 7 days
|
||||||
|
lastSeen: new Date(Date.now() - 30_000).toISOString(),
|
||||||
|
ipAddresses: ['192.168.1.100'],
|
||||||
|
agentVersion: '2.4.1',
|
||||||
|
},
|
||||||
|
];
|
||||||
|
|
||||||
|
const MOCK_GROUPS: DeviceGroup[] = [
|
||||||
|
{
|
||||||
|
id: 'grp-servers',
|
||||||
|
name: 'Servers',
|
||||||
|
description: 'Production and infrastructure servers',
|
||||||
|
deviceCount: 2,
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: 'grp-workstations',
|
||||||
|
name: 'Workstations',
|
||||||
|
description: 'User workstations and laptops',
|
||||||
|
deviceCount: 1,
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: 'grp-devices',
|
||||||
|
name: 'IoT Devices',
|
||||||
|
description: 'Raspberry Pi and other IoT devices',
|
||||||
|
deviceCount: 1,
|
||||||
|
},
|
||||||
|
];
|
||||||
|
|
||||||
|
const DIAGNOSTIC_OUTPUTS: Record<DiagnosticCheckType, string> = {
|
||||||
|
[DiagnosticCheckType.DiskSpace]: `Filesystem Size Used Avail Use% Mounted on
|
||||||
|
/dev/sda1 1008G 234G 724G 25% /
|
||||||
|
tmpfs 7.7G 0 7.7G 0% /dev/shm
|
||||||
|
/dev/sda2 938M 156M 724M 18% /boot
|
||||||
|
`,
|
||||||
|
[DiagnosticCheckType.Services]: `● ssh.service - OpenSSH daemon
|
||||||
|
Loaded: loaded (/lib/systemd/system/ssh.service; enabled; preset: enabled)
|
||||||
|
Active: active (running) since Mon 2026-08-24 07:00:00 UTC; 15h ago
|
||||||
|
Main PID: 1234 (sshd)
|
||||||
|
● nginx.service - A high performance web server and reverse proxy server
|
||||||
|
Loaded: loaded (/lib/systemd/system/nginx.service; enabled; preset: enabled)
|
||||||
|
Active: active (running) since Mon 2026-08-24 07:01:00 UTC; 15h ago
|
||||||
|
● postgresql.service - PostgreSQL RDBMS
|
||||||
|
Loaded: loaded (/lib/systemd/system/postgresql.service; enabled; preset: enabled)
|
||||||
|
Active: active (running) since Mon 2026-08-24 07:02:00 UTC; 15h ago
|
||||||
|
`,
|
||||||
|
[DiagnosticCheckType.Processes]: `USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
|
||||||
|
root 1234 0.0 0.1 16856 5432 ? Ss 07:00 0:01 sshd: /usr/sbin/sshd -D
|
||||||
|
www-data 234567 1.2 0.8 245632 32768 ? Sl 07:01 1:23 nginx: worker process
|
||||||
|
postgres 345678 0.5 1.2 567890 49152 ? Ss 07:02 0:45 postgres: main process
|
||||||
|
`,
|
||||||
|
[DiagnosticCheckType.OSDetails]: `NAME="Ubuntu"
|
||||||
|
VERSION="24.04 LTS (Noble Numbat)"
|
||||||
|
ID=ubuntu
|
||||||
|
ID_LIKE=debian
|
||||||
|
PRETTY_NAME="Ubuntu 24.04 LTS"
|
||||||
|
VERSION_ID="24.04"
|
||||||
|
KERNEL_VERSION="6.8.0-45-generic"
|
||||||
|
`,
|
||||||
|
[DiagnosticCheckType.NetworkState]: `1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
|
||||||
|
inet 127.0.0.1/8 scope host lo
|
||||||
|
valid_lft forever preferred_lft forever
|
||||||
|
inet6 ::1/128 scope host
|
||||||
|
valid_lft forever preferred_lft forever
|
||||||
|
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
|
||||||
|
inet 192.168.1.10/24 brd 192.168.1.255 scope global eth0
|
||||||
|
valid_lft forever preferred_lft forever
|
||||||
|
inet6 fd00::1/64 scope global
|
||||||
|
valid_lft forever preferred_lft forever
|
||||||
|
`,
|
||||||
|
[DiagnosticCheckType.Uptime]: `22:30:00 up 15 days, 4:30, 2 users, load average: 0.15, 0.25, 0.30
|
||||||
|
`,
|
||||||
|
};
|
||||||
|
|
||||||
|
export class MockAdapter implements MeshCentralAdapter {
|
||||||
|
readonly name = 'mock';
|
||||||
|
readonly version = '0.1.0';
|
||||||
|
|
||||||
|
private config: typeof defaultConfig;
|
||||||
|
|
||||||
|
constructor(config: Partial<typeof defaultConfig> = {}) {
|
||||||
|
this.config = { ...defaultConfig, ...config };
|
||||||
|
}
|
||||||
|
|
||||||
|
async listDevices(request?: ListDevicesRequest): Promise<Device[]> {
|
||||||
|
let devices = MOCK_DEVICES;
|
||||||
|
|
||||||
|
if (request?.groupId) {
|
||||||
|
devices = devices.filter((d) => d.groupId === request.groupId);
|
||||||
|
}
|
||||||
|
|
||||||
|
return devices;
|
||||||
|
}
|
||||||
|
|
||||||
|
async getDevice(deviceId: string): Promise<Device> {
|
||||||
|
const device = MOCK_DEVICES.find((d) => d.id === deviceId);
|
||||||
|
|
||||||
|
if (!device) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ResourceNotFound,
|
||||||
|
`Device not found: ${deviceId}`,
|
||||||
|
{ deviceId },
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return device;
|
||||||
|
}
|
||||||
|
|
||||||
|
async listGroups(): Promise<DeviceGroup[]> {
|
||||||
|
return MOCK_GROUPS;
|
||||||
|
}
|
||||||
|
|
||||||
|
async getGroup(groupId: string): Promise<DeviceGroup> {
|
||||||
|
const group = MOCK_GROUPS.find((g) => g.id === groupId);
|
||||||
|
|
||||||
|
if (!group) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ResourceNotFound,
|
||||||
|
`Group not found: ${groupId}`,
|
||||||
|
{ groupId },
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return group;
|
||||||
|
}
|
||||||
|
|
||||||
|
async runDiagnostic(request: RunDiagnosticRequest): Promise<DiagnosticResult> {
|
||||||
|
const { deviceId, checkType, timeoutMs = this.config.timeoutMs, maxOutputLength = this.config.maxOutputLength } =
|
||||||
|
request;
|
||||||
|
|
||||||
|
// Simulate network delay
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, Math.min(timeoutMs, 100)));
|
||||||
|
|
||||||
|
const output = DIAGNOSTIC_OUTPUTS[checkType] || '';
|
||||||
|
|
||||||
|
// Truncate if needed
|
||||||
|
const truncated = output.length > maxOutputLength;
|
||||||
|
const trimmedOutput = truncated ? output.slice(0, maxOutputLength) + '\n...[truncated]' : output;
|
||||||
|
|
||||||
|
return {
|
||||||
|
deviceId,
|
||||||
|
checkType,
|
||||||
|
timestamp: new Date().toISOString(),
|
||||||
|
success: true,
|
||||||
|
output: trimmedOutput,
|
||||||
|
exitCode: 0,
|
||||||
|
outputLength: trimmedOutput.length,
|
||||||
|
maxOutputLength,
|
||||||
|
truncated,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
async healthCheck(): Promise<boolean> {
|
||||||
|
// Mock always healthy
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export function createMockAdapter(config?: Partial<typeof defaultConfig>): MeshCentralAdapter {
|
||||||
|
return new MockAdapter(config);
|
||||||
|
}
|
||||||
|
|
||||||
|
export { DiagnosticCheckType };
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"compilerOptions": {
|
||||||
|
"target": "ES2022",
|
||||||
|
"module": "commonjs",
|
||||||
|
"lib": ["ES2022"],
|
||||||
|
"declaration": true,
|
||||||
|
"strict": true,
|
||||||
|
"noImplicitAny": true,
|
||||||
|
"strictNullChecks": true,
|
||||||
|
"noImplicitThis": true,
|
||||||
|
"alwaysStrict": true,
|
||||||
|
"noUnusedLocals": false,
|
||||||
|
"noUnusedParameters": false,
|
||||||
|
"noImplicitReturns": true,
|
||||||
|
"noFallthroughCasesInSwitch": true,
|
||||||
|
"inlineSources": true,
|
||||||
|
"sourceMap": true,
|
||||||
|
"outDir": "./dist",
|
||||||
|
"rootDir": "./src",
|
||||||
|
"paths": {
|
||||||
|
"@/*": ["./src/*"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"include": ["src/**/*"],
|
||||||
|
"exclude": ["node_modules", "dist", "**/*.test.ts"]
|
||||||
|
}
|
||||||
@@ -0,0 +1,140 @@
|
|||||||
|
# MeshCentral Integration Research
|
||||||
|
|
||||||
|
**Project:** MeshCentral ↔ OpenClaw Bridge
|
||||||
|
**Research date:** 2026-08-24/25 (America/Toronto)
|
||||||
|
**Scope:** research only; no live MeshCentral or infrastructure changes were made.
|
||||||
|
|
||||||
|
## Executive summary
|
||||||
|
|
||||||
|
MeshCentral's most practical supported automation surface is the **official `meshctrl.js` command-line client**, shipped with the MeshCentral npm package. It connects to the server's `wss://.../control.ashx` WebSocket and uses the same control channel as the web application. The current upstream package metadata identifies MeshCentral **1.2.5**, released 2026-08-12, and requires Node.js >=20.
|
||||||
|
|
||||||
|
There is no evidence in the upstream repositories or the GitHub repository search performed on 2026-08-25 of a maintained, general-purpose MeshCentral MCP server. One search result, `spanishdexter/MeshOps`, is an automation-template project for `meshctrl.js`, but had 0 stars and an update timestamp of 2026-03-30; it should not be treated as a mature integration dependency. Recommendation: build a narrow bridge against a local adapter boundary, initially wrapping or reimplementing only the read-only subset of the official MeshCtrl protocol, with version-pinned compatibility tests. Do not expose MeshCentral's raw WebSocket protocol as an OpenClaw tool API.
|
||||||
|
|
||||||
|
**Overall confidence:** High for the existence and broad behavior of MeshCtrl; medium for protocol stability and exact authorization semantics because the control-channel messages are implementation details rather than a separately versioned public REST API; low for third-party MCP adapter availability.
|
||||||
|
|
||||||
|
## Official integration surfaces
|
||||||
|
|
||||||
|
### 1. MeshCtrl (`meshctrl.js`) — preferred starting point
|
||||||
|
|
||||||
|
The official documentation describes MeshCtrl as a Node.js command-line tool installed with MeshCentral. It may run on the server or remotely, logs in over WebSocket, and supports JSON output. Read-only commands relevant to the MVP include:
|
||||||
|
|
||||||
|
- `ServerInfo`, `ServerVersion`, `UserInfo`
|
||||||
|
- `ListDeviceGroups`, `ListDevices`, `DeviceInfo`
|
||||||
|
- `ListEvents` (careful: event data may contain sensitive information)
|
||||||
|
|
||||||
|
The current upstream source lists additional state-changing and high-risk operations, including `RunCommand`, shell/file transfer, device power, user/group management, and device deletion. The bridge must not pass these through merely because the client supports them.
|
||||||
|
|
||||||
|
Observed current source behavior:
|
||||||
|
|
||||||
|
- Default endpoint: `wss://localhost:443/control.ashx`; `--url` accepts `ws://` or `wss://` and appends `/control.ashx`.
|
||||||
|
- Password authentication is sent in an `x-meshauth` WebSocket header containing base64 username, password, and optionally a 2FA token.
|
||||||
|
- A login-key mode can generate a time-limited authentication cookie from an 80-byte hex key; upstream documentation warns that the login-token key can impersonate users and is highly sensitive.
|
||||||
|
- After connection, the client sends JSON actions such as `meshes`, `nodes`, `events`, `serverversion`, and `deviceinfo` and receives JSON responses.
|
||||||
|
- The client is updated with the server and is therefore a useful compatibility reference, but this is not equivalent to a stable, independently versioned API contract.
|
||||||
|
|
||||||
|
**Important security observation:** current upstream `meshctrl.js` source creates WebSocket options with `rejectUnauthorized: false` and a no-op certificate verifier (`onVerifyServer` returns `null`). This means blindly embedding or copying that client can permit a man-in-the-middle attack. The bridge must use a TLS implementation with certificate validation enabled, and should support an explicit private-CA trust bundle or certificate pinning appropriate to the homelab. This finding should be verified against the exact package version selected before implementation.
|
||||||
|
|
||||||
|
### 2. MeshCentral server-side JavaScript/module API
|
||||||
|
|
||||||
|
The main package exports/contains server internals (`meshcentral.js`, database, webserver, plugin and agent managers), but no separately documented, stable remote server API was found in the upstream documentation repository. Loading MeshCentral internals inside the bridge would couple the bridge to private objects, deployment paths, process/runtime state, and the server's upgrade lifecycle. It also risks granting access beyond the integration identity's intended authorization boundary.
|
||||||
|
|
||||||
|
**Recommendation:** do not load MeshCentral as an in-process library for the first implementation. Use a separate process and the authenticated control channel, or a small upstream-compatible adapter behind a typed interface. Revisit a server plugin only if a future requirement demands an event-driven or server-local capability and its lifecycle/security model is documented and tested.
|
||||||
|
|
||||||
|
### 3. Web UI/control protocol
|
||||||
|
|
||||||
|
MeshCtrl uses `control.ashx`, WebSocket JSON messages, and relay/tunnel endpoints for interactive shell/file operations. This is a useful protocol reference but is an internal application protocol. Message names, response shapes, auth cookies, and permissions may change between MeshCentral releases. A bridge should:
|
||||||
|
|
||||||
|
1. Pin and record the MeshCentral version.
|
||||||
|
2. Keep a protocol adapter isolated from OpenClaw schemas.
|
||||||
|
3. Validate response schemas and reject unexpected/ambiguous data.
|
||||||
|
4. Maintain mock fixtures and an integration test matrix for every upgrade.
|
||||||
|
5. Treat all endpoint/device text as untrusted data, not instructions.
|
||||||
|
|
||||||
|
## Authentication and session behavior
|
||||||
|
|
||||||
|
MeshCtrl supports two primary login styles:
|
||||||
|
|
||||||
|
1. **Username/password**, optionally with a TOTP/2FA token. The password is placed in a WebSocket header by the official client; avoid command-line arguments because process listings and shell history can expose them.
|
||||||
|
2. **Server login key**, used to create a login cookie for a specified user/domain. This is powerful impersonation material and should not be used for the bridge unless Rob explicitly chooses it and the key is scoped/protected as well as possible. A key file should never be committed, logged, or mounted broadly.
|
||||||
|
|
||||||
|
The WebSocket session is authenticated at connection time, then receives control actions and responses over the session. The bridge should use one dedicated account and explicitly check that target device/group identifiers are in its configured allowlist, even if MeshCentral also enforces permissions. Authorization should be treated as both server-side and bridge-side defense in depth.
|
||||||
|
|
||||||
|
Open questions about session details that require a controlled test against the actual deployment:
|
||||||
|
|
||||||
|
- Whether the selected MeshCentral account can perform each desired read-only action and which fields are returned.
|
||||||
|
- How sessions expire, how reconnects behave, and whether a reconnect can replay an action.
|
||||||
|
- Exact response/error messages and whether errors are distinguishable from empty results.
|
||||||
|
- Whether the deployment uses a non-default domain URL and/or reverse proxy path.
|
||||||
|
- Whether 2FA is required for the integration account and whether a non-interactive token/key method is acceptable.
|
||||||
|
|
||||||
|
## Version compatibility
|
||||||
|
|
||||||
|
Upstream package metadata observed 2026-08-25:
|
||||||
|
|
||||||
|
- MeshCentral version: `1.2.5`
|
||||||
|
- Published release: 2026-08-12
|
||||||
|
- Git commit: `b09b1d60328de8e2d2f7387561ed51c64011c82a`
|
||||||
|
- Node engine: `>=20.0.0`
|
||||||
|
- WebSocket dependency: `ws` 8.21.1
|
||||||
|
|
||||||
|
The release notes include changes to `meshctrl.js`, including allowing a user ID without a domain and adding server-version output. This reinforces that the bundled client and server are released together and that protocol behavior can change. The bridge should record the tested server version and client/source commit, use semver/commit compatibility checks, and fail closed or enter degraded read-only mode when an unknown version is detected.
|
||||||
|
|
||||||
|
## Existing adapters / MCP servers
|
||||||
|
|
||||||
|
A GitHub repository search for `MeshCentral MCP`, `MeshCentral API client`, and related terms found no clearly maintained general-purpose MCP server as of 2026-08-25. The notable related result was:
|
||||||
|
|
||||||
|
- [spanishdexter/MeshOps](https://github.com/spanishdexter/MeshOps) — workflow automation templates using MeshCentral's `meshctrl.js`; observed 0 stars and updated 2026-03-30. This may provide ideas, but is not sufficient evidence of maintained protocol support or security review.
|
||||||
|
|
||||||
|
No third-party adapter should be installed or granted credentials without reviewing source, release activity, dependency health, license, target scope, logging, and TLS behavior. A local OpenClaw MCP/tool wrapper owned by this project is preferable to adopting an unverified adapter, while retaining a replaceable MeshCentral adapter interface.
|
||||||
|
|
||||||
|
## Security implications and design requirements
|
||||||
|
|
||||||
|
MeshCentral is a remote-management control plane. Even read-only inventory can disclose hostnames, OS versions, IP addresses, uptime, user/session information, and event history. Diagnostics and command execution can become full remote code execution on an endpoint.
|
||||||
|
|
||||||
|
Required controls for the bridge:
|
||||||
|
|
||||||
|
- Dedicated least-privilege MeshCentral identity; never Rob's primary admin account.
|
||||||
|
- Bridge and MeshCentral restricted to the trusted management network; no public MCP endpoint.
|
||||||
|
- Validated TLS certificates; do not inherit upstream MeshCtrl's `rejectUnauthorized: false` behavior.
|
||||||
|
- Secrets in a protected runtime store/environment with restrictive permissions; never URLs, headers, passwords, login keys, or cookies in logs.
|
||||||
|
- Typed read-only operations first; no arbitrary shell text in the initial release.
|
||||||
|
- Explicit device and group allowlists; reject ambiguous names and require stable IDs where possible.
|
||||||
|
- Timeouts, response-size caps, concurrency/rate limits, reconnect backoff, and cancellation.
|
||||||
|
- Audit records containing authenticated principal, operation, target, request ID, timestamps, outcome, and truncation status—but not secrets or raw sensitive output by default.
|
||||||
|
- Treat device names, event text, command output, and logs as untrusted content to defend against prompt injection.
|
||||||
|
- Fail closed on uncertain auth, target resolution, server version, TLS, or partial execution.
|
||||||
|
- Separate read-only, diagnostic, reversible, disruptive, and destructive capabilities. Require immediate confirmation for every state-changing operation; keep destructive operations disabled.
|
||||||
|
|
||||||
|
## Recommended implementation path
|
||||||
|
|
||||||
|
1. Record Rob's actual MeshCentral version, domain/path, TLS CA, network placement, and a non-production test device.
|
||||||
|
2. Implement a `MeshCentralClient` interface with typed methods for server info, groups, device inventory, device metadata, and (only after review) events.
|
||||||
|
3. Add a MeshCtrl-compatible transport adapter with strict TLS validation and schema validation; keep it behind the interface.
|
||||||
|
4. Use mock WebSocket fixtures for auth success/failure, expired session, reconnect, malformed response, unknown version, oversized output, and permission denial.
|
||||||
|
5. Test against one selected non-production device only after explicit approval and after documenting credentials/secret storage.
|
||||||
|
6. Add diagnostics only as named allowlisted operations. Add actions only after a separate confirmation/audit design review.
|
||||||
|
|
||||||
|
## Open questions for Rob
|
||||||
|
|
||||||
|
1. What exact MeshCentral version and domain/path are deployed?
|
||||||
|
2. Is MeshCentral reachable only on the trusted LAN/VPN, or through public ingress/reverse proxy?
|
||||||
|
3. Which device group and one non-production test device may be allowlisted?
|
||||||
|
4. Should the bridge account be local MeshCentral credentials with 2FA, or is another supported identity provider in use?
|
||||||
|
5. Where may the bridge secret and audit logs be stored, and what retention is acceptable?
|
||||||
|
6. Does the MeshCentral TLS certificate chain validate from the proposed bridge host? If not, where is the private CA bundle managed?
|
||||||
|
7. Are event history and endpoint metadata allowed in OpenClaw responses, given possible personal/sensitive data?
|
||||||
|
8. Which initial diagnostics are genuinely needed, and what exact typed checks/limits should be permitted?
|
||||||
|
9. What is the required behavior on a MeshCentral upgrade: block unknown versions, or permit read-only operation after a compatibility check?
|
||||||
|
|
||||||
|
## Sources (accessed 2026-08-25)
|
||||||
|
|
||||||
|
1. MeshCentral source repository: https://github.com/Ylianst/MeshCentral
|
||||||
|
2. Current package metadata (version, Node requirement, dependencies): https://raw.githubusercontent.com/Ylianst/MeshCentral/master/package.json
|
||||||
|
3. Official MeshCtrl source (endpoint, auth headers, actions, TLS options): https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshctrl.js
|
||||||
|
4. Official MeshCtrl guide (WebSocket behavior, login methods, commands, login-key warning): https://docs.meshcentral.com/meshctrl/
|
||||||
|
5. Official MeshCentral security guidance (rate limiting, 2FA, TLS settings): https://docs.meshcentral.com/meshcentral/security/
|
||||||
|
6. Official secure-installation guidance (low-privilege account and manual updates): https://docs.meshcentral.com/install/security/secure/
|
||||||
|
7. Latest release API record observed during research (1.2.5, published 2026-08-12): https://api.github.com/repos/Ylianst/MeshCentral/releases/latest
|
||||||
|
8. Related third-party search result: https://github.com/spanishdexter/MeshOps
|
||||||
|
|
||||||
|
URLs and claims above are research references, not authorization to connect to or change live systems.
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
# MeshCentral ↔ OpenClaw Bridge — Final Hardening Review
|
||||||
|
|
||||||
|
**Date:** 2026-08-25
|
||||||
|
**Reviewer:** Clawdia (manager review)
|
||||||
|
**Scope:** Current implementation under `implementation/src/`
|
||||||
|
**Purpose:** Disposition the earlier independent review against the hardened local source.
|
||||||
|
|
||||||
|
## Verdict
|
||||||
|
|
||||||
|
**Local read-only MVP gate: PASS.** The implementation passes the local verification gate and contains the required controls for preparing a tightly scoped live read-only test.
|
||||||
|
|
||||||
|
**Live test: NOT YET APPROVED.** A live connection remains gated on deployment-specific checks and Rob's explicit approval immediately before execution.
|
||||||
|
|
||||||
|
## Verification evidence
|
||||||
|
|
||||||
|
- `npm test -- --runInBand`: **11 suites, 90 tests passed**
|
||||||
|
- `npm run build`: **passed**
|
||||||
|
- `npm run lint`: **passed with no errors or warnings**
|
||||||
|
- No live MeshCentral connection has been attempted.
|
||||||
|
|
||||||
|
## Prior finding disposition
|
||||||
|
|
||||||
|
| Finding | Current disposition | Evidence / residual risk |
|
||||||
|
|---|---|---|
|
||||||
|
| Credential/error leakage | **Addressed locally** | Credentials are validated before use; user-facing configuration failures are generic; audit/logging paths use redacted summaries. Residual risk: live secret handling still requires a protected runtime mechanism and operational verification. |
|
||||||
|
| Credential validation/sanitization | **Addressed locally** | `validateCredentials()` is called before encoding/storage; credentials are never intentionally logged. Residual risk: the control-channel auth header necessarily contains the credential material in memory during connection. |
|
||||||
|
| TLS validation | **Addressed locally** | WebSocket options explicitly set `rejectUnauthorized: true`; no bypass is present. Residual risk: the actual deployment certificate chain/private CA must be verified from the bridge host. |
|
||||||
|
| Response validation and size limits | **Addressed locally** | Responses are size-bounded and parsed/validated; action-specific schemas and action matching are enforced. Residual risk: protocol compatibility with the deployed server remains unverified until a read-only test. |
|
||||||
|
| Request concurrency/rate limiting | **Addressed locally** | Semaphore and token-bucket controls apply to outbound requests; configuration has bounded validation and safe defaults. Residual risk: limits are protective controls, not a substitute for MeshCentral capacity testing. |
|
||||||
|
| Device/group allowlists | **Addressed locally** | Adapter validates allowlist entries and filters/checks device/group targets. Residual risk: the intended PVE3 identifier and group mapping must be confirmed before live use. |
|
||||||
|
| Sensitive data in logs | **Addressed locally with operational caveat** | Structured logger and audit utilities redact credential keys, auth headers, token-like values, and encoded secret patterns. Residual risk: logs still contain inventory metadata and must be stored with appropriate permissions/retention. |
|
||||||
|
| Separate handshake/request timeout | **Deferred, non-blocking** | A single bounded timeout is used for connection and requests. This does not expand capability or permit unsafe actions; it should be revisited after live read-only validation. |
|
||||||
|
| Automatic reconnection/session renewal | **Deferred, non-blocking for first test** | No automatic reconnect is enabled, reducing replay risk. A dropped session fails rather than autonomously replaying requests. |
|
||||||
|
| Structured audit logging | **Addressed locally** | Adapter and client use the controlled logger for audit events; redaction is applied. Operational sink/retention must be selected before deployment. |
|
||||||
|
|
||||||
|
## Live-test entry criteria still open
|
||||||
|
|
||||||
|
These are deployment facts, not local code failures:
|
||||||
|
|
||||||
|
1. Confirm `mesh.ledrew.me` resolves to the intended internal MeshCentral service from the proposed bridge host.
|
||||||
|
2. Confirm the correct control-channel URL/path and whether TLS is terminated at a reverse proxy.
|
||||||
|
3. Verify the certificate chain or approved private CA bundle from the bridge host; never disable verification.
|
||||||
|
4. Confirm `sa_clawdia` is dedicated and read-only for this first test.
|
||||||
|
5. Confirm the exact PVE3 device ID/group and configure it as the sole allowed target.
|
||||||
|
6. Inject the credential through a protected runtime secret mechanism; do not place it in source, prompts, command arguments, or logs.
|
||||||
|
7. Confirm audit-log destination, permissions, and retention.
|
||||||
|
8. Obtain Rob's explicit approval immediately before the live connection.
|
||||||
|
|
||||||
|
## Scope restrictions for first live test
|
||||||
|
|
||||||
|
Allowed only:
|
||||||
|
|
||||||
|
- Authentication/connection health check
|
||||||
|
- Server version
|
||||||
|
- Device groups
|
||||||
|
- Device inventory
|
||||||
|
- Selected metadata for the single approved PVE3 target
|
||||||
|
|
||||||
|
Prohibited:
|
||||||
|
|
||||||
|
- Diagnostics that execute commands
|
||||||
|
- Remote shell, file transfer, or arbitrary command execution
|
||||||
|
- Reboots, shutdowns, service changes, or any state-changing action
|
||||||
|
- PVE1/PVE2 production-cluster targeting
|
||||||
|
- Public exposure of the bridge or MeshCentral
|
||||||
|
|
||||||
|
## Risk acceptance
|
||||||
|
|
||||||
|
No deferred feature is accepted as a reason to enable remote actions. The deferred timeout separation and reconnect behavior are explicitly **non-blocking only for a single, read-only, single-target test** and remain unsuitable for production fleet operation without further design/review.
|
||||||
|
|
||||||
|
The live-test gate remains closed until the entry criteria above are checked and Rob approves the specific read-only procedure immediately before execution.
|
||||||
@@ -0,0 +1,376 @@
|
|||||||
|
# Live Adapter Security Review
|
||||||
|
|
||||||
|
**Date:** 2026-08-25
|
||||||
|
**Scope:** `/home/ledadmin/projects/meshcentral-openclaw-bridge/implementation`
|
||||||
|
**Reviewer:** Subagent (depth 1/1)
|
||||||
|
**Status:** Independent security/protocol review
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
|
||||||
|
The MeshCentral ↔ OpenClaw bridge implementation demonstrates **good security hygiene in design intent**, but contains **multiple high-severity implementation gaps** that prevent safe live testing in its current state. The TLS security controls are correctly configured (no `rejectUnauthorized: false`), but the codebase lacks credential sanitization, output validation, and proper error masking—critical for production deployment.
|
||||||
|
|
||||||
|
**Recommendation:** Live testing is **NOT SAFE** in its current state. Address all high-severity findings before any live deployment.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview of Reviewed Files
|
||||||
|
|
||||||
|
| File | Purpose | Reviewed |
|
||||||
|
|------|---------|----------|
|
||||||
|
| `research/INTEGRATION-RESEARCH.md` | Protocol analysis and threat model | ✅ |
|
||||||
|
| `SECURITY.md` | Security requirements and action classes | ✅ |
|
||||||
|
| `src/meshctrl-client.ts` | WebSocket client for MeshCentral protocol | ✅ |
|
||||||
|
| `src/adapter.ts` | Real adapter implementation | ✅ |
|
||||||
|
| `src/contracts.ts` | Zod schemas and type definitions | ✅ |
|
||||||
|
| `package.json` | Dependencies and scripts | ✅ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Test Results
|
||||||
|
|
||||||
|
The implementation has a robust test suite:
|
||||||
|
|
||||||
|
| Command | Result |
|
||||||
|
|---------|--------|
|
||||||
|
| `npm run build` | ✅ Pass (no errors) |
|
||||||
|
| `npm run lint` | ✅ Pass (no errors) |
|
||||||
|
| `npm test` | ✅ 52/52 tests pass (8 test suites) |
|
||||||
|
|
||||||
|
Tests cover:
|
||||||
|
- Device status handling
|
||||||
|
- Adapter factory patterns
|
||||||
|
- Contract validation (Zod schemas)
|
||||||
|
- Output truncation and limits
|
||||||
|
- Group filtering
|
||||||
|
- Integration workflows
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Findings by Severity
|
||||||
|
|
||||||
|
### 🔴 HIGH SEVERITY (Blocking live testing)
|
||||||
|
|
||||||
|
#### 1. **Credentials in Error Messages**
|
||||||
|
**Location:** `adapter.ts`, `_validateConfig()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
if (hasUsername !== hasPassword) {
|
||||||
|
throw new BridgeError(
|
||||||
|
ErrorCodes.ConfigurationInvalid,
|
||||||
|
'Both username and password must be provided (or neither for mock mode)',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** The error handling does not sanitize or mask credential-related information. If credentials are partially configured, the system should not reveal which component is missing.
|
||||||
|
|
||||||
|
**Risk:** Credential enumeration and configuration leakage in logs/monitoring.
|
||||||
|
|
||||||
|
**Remediation:**
|
||||||
|
- Use generic error messages for credential validation failures
|
||||||
|
- Log detailed errors only to secure audit logs (not user-facing responses)
|
||||||
|
- Never include credential field names in error messages
|
||||||
|
|
||||||
|
#### 2. **No Credential Sanitization Before Use**
|
||||||
|
**Location:** `meshctrl-client.ts`, `encodeAuthHeader()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export function encodeAuthHeader(credentials: AuthCredentials): string {
|
||||||
|
const { username, password, totpToken } = credentials;
|
||||||
|
if (totpToken) {
|
||||||
|
return Buffer.from(`${username}:${password}:${totpToken}`).toString('base64');
|
||||||
|
}
|
||||||
|
return Buffer.from(`${username}:${password}`).toString('base64');
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** Credentials are used directly without validation or sanitization. No check for special characters, empty strings, or malicious payloads in username/password.
|
||||||
|
|
||||||
|
**Risk:**
|
||||||
|
- Authentication bypass via malformed credentials
|
||||||
|
- Protocol injection via special characters in username/password
|
||||||
|
- TOTP token leakage if exposed
|
||||||
|
|
||||||
|
**Remediation:**
|
||||||
|
- Validate username/password meet minimum length requirements
|
||||||
|
- Sanitize/escape special characters before encoding
|
||||||
|
- Add explicit input validation before credential handling
|
||||||
|
|
||||||
|
#### 3. **Missing Certificate Validation Configuration**
|
||||||
|
**Location:** `meshctrl-client.ts`, `MeshCtrlClient.connect()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
this.ws = new WebSocket(wsUrl, {
|
||||||
|
perMessageDeflate: false,
|
||||||
|
headers: {
|
||||||
|
'x-meshauth': authHeader,
|
||||||
|
},
|
||||||
|
// Important: no TLS bypass - use default certificate validation
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** While the code comments state "no TLS bypass", it does not explicitly configure certificate validation or support custom CA bundles. The `ws` library defaults may vary by environment.
|
||||||
|
|
||||||
|
**Risk:** Inconsistent certificate validation behavior across deployment environments.
|
||||||
|
|
||||||
|
**Remediation:**
|
||||||
|
- Explicitly set `rejectUnauthorized: true` (default, but make explicit)
|
||||||
|
- Add support for custom CA bundle via environment variable
|
||||||
|
- Document TLS configuration requirements
|
||||||
|
|
||||||
|
#### 4. **No Response Validation on WebSocket Messages**
|
||||||
|
**Location:** `meshctrl-client.ts`, `_sendRequestInternal()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const handleResponse = (data: Buffer | string): void => {
|
||||||
|
try {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
const response = parseResponse(data.toString());
|
||||||
|
// ...
|
||||||
|
} catch (error) {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
this._cleanup();
|
||||||
|
reject(error instanceof Error ? error : new Error('Unknown error'));
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** Responses are parsed without schema validation against the expected `MeshCtrlResponse` contract. Malformed or malicious responses could cause undefined behavior.
|
||||||
|
|
||||||
|
**Risk:** Protocol downgrade attacks, response injection, or memory exhaustion from oversized responses.
|
||||||
|
|
||||||
|
**Remediation:**
|
||||||
|
- Validate all responses against Zod schemas (already available in `contracts.ts`)
|
||||||
|
- Enforce `MAX_RESPONSE_SIZE` limit before parsing
|
||||||
|
- Reject responses with unexpected fields
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟡 MEDIUM SEVERITY (Should address before production)
|
||||||
|
|
||||||
|
#### 5. **No Rate Limiting or Concurrent Request Throttling**
|
||||||
|
**Location:** `meshctrl-client.ts`, `_sendWithRetry()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
async _sendWithRetry(request: MeshCtrlRequest, maxRetries: number): Promise<MeshCtrlResponse> {
|
||||||
|
let lastError: Error | null = null;
|
||||||
|
for (let attempt = 1; attempt <= maxRetries; attempt++) {
|
||||||
|
try {
|
||||||
|
return await this._sendRequestInternal(request);
|
||||||
|
} catch (error) {
|
||||||
|
lastError = error instanceof Error ? error : new Error('Unknown error');
|
||||||
|
if (attempt < maxRetries) {
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, 100 * attempt));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
throw new Error(`Request failed after ${maxRetries} attempts: ${lastError?.message}`);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** No global rate limiting. Multiple concurrent requests can flood the MeshCentral server, potentially triggering denial-of-service protections.
|
||||||
|
|
||||||
|
**Risk:** Collateral damage to other services, connection throttling, or account lockout.
|
||||||
|
|
||||||
|
**Remediation:**
|
||||||
|
- Implement per-adapter request rate limiting (e.g., 5 requests/second)
|
||||||
|
- Add circuit breaker for repeated failures
|
||||||
|
- Document rate limits in security configuration
|
||||||
|
|
||||||
|
#### 6. **No Input Validation on Device/Group IDs**
|
||||||
|
**Location:** `adapter.ts`, `_isDeviceAllowed()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
private _isDeviceAllowed(deviceId: string): boolean {
|
||||||
|
const { deviceAllowlist, groupAllowlist } = this.config;
|
||||||
|
if (!deviceAllowlist && !groupAllowlist) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
if (deviceAllowlist && deviceAllowlist.includes(deviceId)) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** Device/group IDs are used directly in allowlist lookups without sanitization or regex validation.
|
||||||
|
|
||||||
|
**Risk:** Path traversal or injection via malicious device IDs in allowlist configuration.
|
||||||
|
|
||||||
|
**Remediation:**
|
||||||
|
- Validate IDs against allowed character set (alphanumeric, hyphens, underscores)
|
||||||
|
- Escape special regex characters if used in allowlist patterns
|
||||||
|
- Document allowed ID formats
|
||||||
|
|
||||||
|
#### 7. **Sensitive Data in Logs**
|
||||||
|
**Location:** Multiple places in `adapter.ts`
|
||||||
|
|
||||||
|
The code uses generic error handling but does not explicitly prevent credential or token leakage in logs.
|
||||||
|
|
||||||
|
**Risk:** Accidental credential exposure via logging systems.
|
||||||
|
|
||||||
|
**Remediation:**
|
||||||
|
- Implement structured logging with automatic secret redaction
|
||||||
|
- Add `secret` annotation to credential fields for automatic masking
|
||||||
|
- Review all error paths for potential leakage
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟢 LOW SEVERITY (Nice to have)
|
||||||
|
|
||||||
|
#### 8. **No Timeout Configuration for WebSocket Handshake**
|
||||||
|
**Location:** `meshctrl-client.ts`, `connect()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
await new Promise<void>((resolve, reject) => {
|
||||||
|
const timeout = setTimeout(() => {
|
||||||
|
this._cleanup();
|
||||||
|
reject(new Error(`Connection timed out after ${this.timeoutMs}ms`));
|
||||||
|
}, this.timeoutMs);
|
||||||
|
// ...
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** The same timeout is used for both connection establishment and request/response cycles. Connection timeouts are typically shorter than request timeouts.
|
||||||
|
|
||||||
|
**Recommendation:** Separate `connectionTimeoutMs` from `requestTimeoutMs`.
|
||||||
|
|
||||||
|
#### 9. **No Session Renewal or Reconnection Strategy**
|
||||||
|
**Location:** `adapter.ts`, `_ensureConnected()`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
private async _ensureConnected(): Promise<void> {
|
||||||
|
if (this.connected) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
// ...
|
||||||
|
await this.client!.connect(this.credentials);
|
||||||
|
this.connected = true;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue:** If the WebSocket connection drops, there is no automatic reconnection logic. The adapter must be destroyed and recreated.
|
||||||
|
|
||||||
|
**Recommendation:** Implement exponential backoff reconnection with maximum retry count.
|
||||||
|
|
||||||
|
#### 10. **Missing Audit Logging**
|
||||||
|
**Location:** `adapter.ts`, all public methods
|
||||||
|
|
||||||
|
The code lacks structured audit logging for security events.
|
||||||
|
|
||||||
|
**Recommendation:**
|
||||||
|
- Log authentication successes/failures
|
||||||
|
- Log allowlist violations
|
||||||
|
- Log request IDs and timestamps for all operations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Protocol Analysis Summary
|
||||||
|
|
||||||
|
### ✅ Correctly Implemented
|
||||||
|
|
||||||
|
| Feature | Status |
|
||||||
|
|---------|--------|
|
||||||
|
| TLS validation (no `rejectUnauthorized: false`) | ✅ Correct |
|
||||||
|
| WebSocket URL construction (`wss://` for HTTPS) | ✅ Correct |
|
||||||
|
| `x-meshauth` header encoding (base64 username:password) | ✅ Correct |
|
||||||
|
| Request/response ID matching | ✅ Correct |
|
||||||
|
| Typed contract schemas (Zod) | ✅ Correct |
|
||||||
|
| Allowlist-based filtering | ✅ Correct |
|
||||||
|
|
||||||
|
### ⚠️ Needs Hardening
|
||||||
|
|
||||||
|
| Feature | Issue |
|
||||||
|
|---------|-------|
|
||||||
|
| Credential validation | Missing input sanitization |
|
||||||
|
| Response validation | No schema enforcement |
|
||||||
|
| Error handling | Potential credential leakage |
|
||||||
|
| Rate limiting | Not implemented |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Live Testing Safety Assessment
|
||||||
|
|
||||||
|
### ❌ Current State: **NOT SAFE**
|
||||||
|
|
||||||
|
**Blocking Issues:**
|
||||||
|
1. Credentials in error messages
|
||||||
|
2. No credential sanitization
|
||||||
|
3. Missing response validation
|
||||||
|
|
||||||
|
**Conditional Safety:**
|
||||||
|
- If deployed on an isolated, air-gapped management network with:
|
||||||
|
- Dedicated non-admin MeshCentral account
|
||||||
|
- Strict firewall rules (outbound only to MeshCentral)
|
||||||
|
- Audit logging enabled
|
||||||
|
- No public ingress
|
||||||
|
|
||||||
|
### ✅ After Remediation: **CONDITIONALLY SAFE**
|
||||||
|
|
||||||
|
The implementation can be made safe for live testing with the following changes:
|
||||||
|
|
||||||
|
1. **Input Validation:** Add sanitization for all credential and ID fields
|
||||||
|
2. **Response Validation:** Enforce Zod schema validation on all WebSocket responses
|
||||||
|
3. **Error Handling:** Remove credential-related details from user-facing errors
|
||||||
|
4. **Rate Limiting:** Implement request throttling to prevent abuse
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recommendations Summary
|
||||||
|
|
||||||
|
| Priority | Action |
|
||||||
|
|----------|--------|
|
||||||
|
| 🔴 **HIGH** | Implement credential sanitization and validation |
|
||||||
|
| 🔴 **HIGH** | Add response schema validation (Zod) for all WebSocket responses |
|
||||||
|
| 🔴 **HIGH** | Sanitize error messages to prevent credential leakage |
|
||||||
|
| 🟡 **MEDIUM** | Add rate limiting for concurrent requests |
|
||||||
|
| 🟡 **MEDIUM** | Validate device/group IDs against allowed character set |
|
||||||
|
| 🟢 **LOW** | Implement structured audit logging |
|
||||||
|
| 🟢 **LOW** | Add separate connection/request timeout configuration |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendices
|
||||||
|
|
||||||
|
### A. Test Coverage Summary
|
||||||
|
|
||||||
|
| Test Suite | Tests Passed | Status |
|
||||||
|
|-----------|-------------|--------|
|
||||||
|
| timeout.test.ts | 4/4 | ✅ |
|
||||||
|
| device-status.test.ts | 6/6 | ✅ |
|
||||||
|
| adapter-factory.test.ts | 3/3 | ✅ |
|
||||||
|
| contracts.test.ts | 5/5 | ✅ |
|
||||||
|
| group-filtering.test.ts | 4/4 | ✅ |
|
||||||
|
| mock-data-loader.test.ts | 2/2 | ✅ |
|
||||||
|
| integration.test.ts | 8/8 | ✅ |
|
||||||
|
| mock-adapter.test.ts | 20/20 | ✅ |
|
||||||
|
|
||||||
|
### B. Dependency Security
|
||||||
|
|
||||||
|
| Package | Version | Known Vulnerabilities |
|
||||||
|
|---------|---------|----------------------|
|
||||||
|
| `ws` | 8.21.3 | None reported (as of 2026-08-25) |
|
||||||
|
| `zod` | 3.24.2 | None reported (as of 2026-08-25) |
|
||||||
|
| `axios` | 1.8.1 | None reported (as of 2026-08-25) |
|
||||||
|
|
||||||
|
### C. Protocol References
|
||||||
|
|
||||||
|
- MeshCentral version: 1.2.5 (released 2026-08-12)
|
||||||
|
- Control endpoint: `/control.ashx` (WebSocket)
|
||||||
|
- Auth header: `x-meshauth` (base64 encoded credentials)
|
||||||
|
- Actions: `serverversion`, `userinfo`, `meshes`, `nodes`, `events`, `deviceinfo`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The bridge implementation demonstrates a solid understanding of security principles in its design, particularly around TLS validation and allowlist enforcement. However, the current code contains critical gaps in credential handling, input validation, and error sanitization that must be addressed before any live deployment.
|
||||||
|
|
||||||
|
**Final Verdict:** **DO NOT ENABLE LIVE TESTING** until the three high-severity findings are remediated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Review completed: 2026-08-25 01:45 EDT*
|
||||||
|
*Subagent session: ca174557-cd3e-4d97-90a9-31efee68aebd*
|
||||||
@@ -0,0 +1,491 @@
|
|||||||
|
# Review Report: MeshCentral ↔ OpenClaw Bridge
|
||||||
|
|
||||||
|
**Review Date:** 2026-08-24
|
||||||
|
**Reviewer:** Independent subagent (clawdia review flow)
|
||||||
|
**Scope:** Implementation under `/home/ledadmin/projects/meshcentral-openclaw-bridge/implementation/`
|
||||||
|
**Reference Docs:** PROJECT.md, SECURITY.md, research/INTEGRATION-RESEARCH.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
|
||||||
|
The implementation provides a well-structured scaffold for the MeshCentral ↔ OpenClaw bridge with solid contracts, typed schemas via Zod, and comprehensive mock-based testing. However, **the critical "real" adapter is completely unimplemented**, leaving only the mock path operational. The current codebase has three categories of issues:
|
||||||
|
|
||||||
|
1. **Critical:** Unimplemented real adapter (`MeshCentralRealAdapter`) with dangerous defaults (insecure TLS, no auth).
|
||||||
|
2. **High:** Test failures indicate missing error message alignment; linting configuration incomplete.
|
||||||
|
3. **Medium:** Diagnostic output sanitization and prompt-injection protection not addressed.
|
||||||
|
|
||||||
|
**Test Results:**
|
||||||
|
- 50 tests pass
|
||||||
|
- 2 tests fail (expectation mismatch on error message string, not logic)
|
||||||
|
- `npm run build` fails with TypeScript errors in test setup
|
||||||
|
- `npm run lint` fails due to missing ESLint configuration
|
||||||
|
|
||||||
|
**Recommendation:** Do **not** proceed with live MeshCentral integration until the real adapter is implemented according to security requirements and all test/lint failures are resolved.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Severity-Ranked Findings
|
||||||
|
|
||||||
|
### 🔴 CRITICAL: Real adapter unimplemented with dangerous TLS defaults
|
||||||
|
|
||||||
|
**Location:** `src/adapter.ts:35-48`, `healthCheck()` method
|
||||||
|
**Severity:** Critical
|
||||||
|
|
||||||
|
The `MeshCentralRealAdapter.healthCheck()` method uses raw `fetch` with no TLS validation options:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
async healthCheck(): Promise<boolean> {
|
||||||
|
try {
|
||||||
|
const response = await fetch(`${this.config.meshCentralUrl}/api`, {
|
||||||
|
method: 'GET',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
});
|
||||||
|
return response.ok;
|
||||||
|
} catch {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issues:**
|
||||||
|
- No certificate verification (relies on Node.js default, which may not validate against internal CA).
|
||||||
|
- `fetch` does not support WebSocket connections; MeshCentral's control API uses `wss://.../control.ashx`, not `/api`.
|
||||||
|
- Research found upstream `meshctrl.js` uses `rejectUnauthorized: false`—this should be explicitly avoided.
|
||||||
|
- No support for meshctrl-style WebSocket authentication (`x-meshauth` header with base64-encoded credentials).
|
||||||
|
|
||||||
|
**Attack Surface:** MITM attack, credential theft via insecure WebSocket upgrade.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Replace `fetch` with a proper WebSocket client (`ws` package, already in dependencies).
|
||||||
|
- Enable TLS certificate validation (do **not** disable it).
|
||||||
|
- Support custom CA bundle for internal MeshCentral deployments.
|
||||||
|
- Implement meshctrl protocol handshake (research confirms `wss://host:port/control.ashx`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🔴 CRITICAL: No authentication or authorization implementation
|
||||||
|
|
||||||
|
**Location:** `src/adapter.ts` (entire file)
|
||||||
|
**Severity:** Critical
|
||||||
|
|
||||||
|
The research document explicitly identifies two authentication modes:
|
||||||
|
1. Username/password via `x-meshauth` WebSocket header (base64 encoded).
|
||||||
|
2. Server login key (highly sensitive—should not be used for the bridge).
|
||||||
|
|
||||||
|
**Current State:** The real adapter has no authentication mechanism. It does not:
|
||||||
|
- Accept or validate credentials.
|
||||||
|
- Support login keys (even in config).
|
||||||
|
- Manage WebSocket sessions or reconnects.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Add `username`, `password` (or `loginKey`) to `BridgeConfig`.
|
||||||
|
- Implement `x-meshauth` header encoding per upstream `meshctrl.js` source.
|
||||||
|
- Store secrets in environment or protected file with restrictive permissions (0600).
|
||||||
|
- Fail closed if credentials are missing or invalid.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟠 HIGH: Test expectation mismatch (non-blocking but indicates incomplete validation)
|
||||||
|
|
||||||
|
**Location:** `src/__tests__/mock-adapter.test.ts:56,86`
|
||||||
|
**Severity:** High
|
||||||
|
|
||||||
|
Tests expect error message substring `"Resource not found"` but actual errors use more specific messages:
|
||||||
|
|
||||||
|
| Test | Expected | Actual |
|
||||||
|
|------|----------|--------|
|
||||||
|
| `getDevice` non-existent | `"Resource not found"` | `"Device not found: nonexistent"` |
|
||||||
|
| `getGroup` non-existent | `"Resource not found"` | `"Group not found: nonexistent"` |
|
||||||
|
|
||||||
|
**Fix:** Update test expectations to match the current error messages, or standardize error messages across the codebase.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Recommendation: Use consistent prefix for all resource-not-found errors
|
||||||
|
`Resource not found: device ${deviceId}`
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟠 HIGH: TypeScript build fails in test setup
|
||||||
|
|
||||||
|
**Location:** `src/__tests__/setup.ts`
|
||||||
|
**Severity:** High
|
||||||
|
|
||||||
|
Build errors prevent compilation and CI validation:
|
||||||
|
|
||||||
|
```
|
||||||
|
src/__tests__/setup.ts(13,15): error TS2428: All declarations of 'Expect' must have identical type parameters.
|
||||||
|
src/__tests__/setup.ts(23,13): error TS7006: Parameter 'received' implicitly has an 'any' type.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Root Cause:** Conflicting `jest` and `jest-extended` types with mismatched generic parameters. The custom matchers declare `Expect<T>` without the required type argument.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Align custom matcher types with `jest` v29 expectations.
|
||||||
|
- Remove duplicate import of `'jest-extended'`.
|
||||||
|
- Use proper typing for `received` parameter.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟠 HIGH: ESLint configuration missing
|
||||||
|
|
||||||
|
**Location:** Project root
|
||||||
|
**Severity:** High
|
||||||
|
|
||||||
|
Lint command fails:
|
||||||
|
|
||||||
|
```
|
||||||
|
ESLint couldn't find a configuration file.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Add `.eslintrc.yml` or `eslint.config.js`.
|
||||||
|
- Enforce TypeScript rules (`@typescript-eslint/`).
|
||||||
|
- Configure import ordering, unused variables, and strict null checks.
|
||||||
|
|
||||||
|
Example minimal config (`eslint.config.js`):
|
||||||
|
```javascript
|
||||||
|
module.exports = {
|
||||||
|
parser: '@typescript-eslint/parser',
|
||||||
|
plugins: ['@typescript-eslint'],
|
||||||
|
extends: [
|
||||||
|
'eslint:recommended',
|
||||||
|
'plugin:@typescript-eslint/recommended',
|
||||||
|
],
|
||||||
|
rules: {
|
||||||
|
'@typescript-eslint/no-explicit-any': 'error',
|
||||||
|
'@typescript-eslint/strict-boolean-expressions': 'off',
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟠 HIGH: Diagnostics produce raw output without sanitization
|
||||||
|
|
||||||
|
**Location:** `src/mock-adapter.ts:54-103`, `DIAGNOSTIC_OUTPUTS`
|
||||||
|
**Severity:** High
|
||||||
|
|
||||||
|
Diagnostic output is hard-coded static strings. Research document warns:
|
||||||
|
- Endpoint command output may contain secrets (passwords, keys).
|
||||||
|
- Device names, logs, and process lists can expose personal data.
|
||||||
|
- Prompt injection via untrusted output is a valid threat.
|
||||||
|
|
||||||
|
**Current State:** No sanitization or escape of special characters, secrets, or prompt-injection vectors.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Implement output sanitization: replace known secret patterns (password=, token=, api_key=).
|
||||||
|
- Truncate or mask sensitive fields in logs.
|
||||||
|
- Add a `sanitizeOutput()` function before returning results.
|
||||||
|
- Consider adding an explicit "safe output only" mode.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟡 MEDIUM: No device/group allowlists
|
||||||
|
|
||||||
|
**Location:** `src/adapter.ts`, `contracts.ts`
|
||||||
|
**Severity:** Medium
|
||||||
|
|
||||||
|
Research document explicitly requires:
|
||||||
|
> Restrict targets using explicit device/group allowlists.
|
||||||
|
|
||||||
|
**Current State:**
|
||||||
|
- Configuration has no `allowedDeviceIds` or `allowedGroupIds`.
|
||||||
|
- No validation that requested devices/groups are in an allowlist.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Add `allowedDeviceIds?: string[]` and `allowedGroupIds?: string[]` to `BridgeConfig`.
|
||||||
|
- Add validation in adapter methods: reject if target not in allowlist (or empty allowlist = all allowed).
|
||||||
|
- Audit log must record whether allowlist check passed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟡 MEDIUM: No audit logging
|
||||||
|
|
||||||
|
**Location:** `src/` (all files)
|
||||||
|
**Severity:** Medium
|
||||||
|
|
||||||
|
Security requirements mandate:
|
||||||
|
> Log authentication events, requests, target, operation, confirmation, result, and timestamp.
|
||||||
|
|
||||||
|
**Current State:** No logging implementation. Debug logs or console.log statements are absent.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Introduce `BridgeLogger` interface with methods:
|
||||||
|
- `logAuth(principal, success, details)`
|
||||||
|
- `logRequest(requestId, principal, operation, target, timestamp)`
|
||||||
|
- `logResult(requestId, success, details)`
|
||||||
|
- Use a structured formatter (JSON) for downstream processing.
|
||||||
|
- Never log secrets (passwords, keys, tokens).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟡 MEDIUM: No connection resilience
|
||||||
|
|
||||||
|
**Location:** `src/adapter.ts`
|
||||||
|
**Severity:** Medium
|
||||||
|
|
||||||
|
Research document notes:
|
||||||
|
> Whether sessions expire, how reconnects behave, and whether a reconnect can replay an action.
|
||||||
|
|
||||||
|
**Current State:** No retry logic, backoff, or session management.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Add `maxRetries`, `retryBackoffMs` to config.
|
||||||
|
- Implement exponential backoff on WebSocket connect failures.
|
||||||
|
- Add reconnect guard to prevent duplicate action replay (e.g., request ID deduplication).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟡 MEDIUM: No version compatibility checking
|
||||||
|
|
||||||
|
**Location:** `src/adapter.ts`, ` contracts.ts`
|
||||||
|
**Severity:** Medium
|
||||||
|
|
||||||
|
Research document warns:
|
||||||
|
> The bridge should record the tested server version and client/source commit, use semver/commit compatibility checks, and fail closed or enter degraded read-only mode when an unknown version is detected.
|
||||||
|
|
||||||
|
**Current State:** No MeshCentral version check.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Add `serverVersion` field to adapter metadata.
|
||||||
|
- Fetch version on connect (e.g., via `ServerInfo` control message).
|
||||||
|
- Define supported version range; fail closed if incompatible.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟡 MEDIUM: Diagnostics allow all check types without policy
|
||||||
|
|
||||||
|
**Location:** `src/contracts.ts`, `mock-adapter.ts`
|
||||||
|
**Severity:** Medium
|
||||||
|
|
||||||
|
Research document requires:
|
||||||
|
> Define an allowlisted set of diagnostic checks... Restrict execution by device/group allowlist and command policy.
|
||||||
|
|
||||||
|
**Current State:**
|
||||||
|
- All `DiagnosticCheckType` values are enabled by default.
|
||||||
|
- No policy mapping check types to permitted device groups.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Add `diagnosticPolicy` config with allowed check types per group/device.
|
||||||
|
- Example:
|
||||||
|
```typescript
|
||||||
|
diagnosticPolicy: {
|
||||||
|
'grp-servers': ['diskSpace', 'uptime'],
|
||||||
|
'*': [],
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- Reject diagnostic requests not in policy.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟡 MEDIUM: No timeout enforcement on real adapter
|
||||||
|
|
||||||
|
**Location:** `src/adapter.ts`
|
||||||
|
**Severity:** Medium
|
||||||
|
|
||||||
|
The `healthCheck()` method has no timeout; `fetch` will hang indefinitely by default.
|
||||||
|
|
||||||
|
**Required Fix:**
|
||||||
|
- Use an AbortController with a configurable timeout.
|
||||||
|
- Reject with `ErrorCodes.TimeoutExceeded` if exceeded.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🟢 LOW: Diagnostic output truncation inconsistent
|
||||||
|
|
||||||
|
**Location:** `src/mock-adapter.ts`
|
||||||
|
**Severity:** Low
|
||||||
|
|
||||||
|
Truncation is simulated but not tested for edge cases:
|
||||||
|
- What happens if `maxOutputLength` is 0?
|
||||||
|
- What happens if output is exactly at the limit?
|
||||||
|
|
||||||
|
**Test Gap:** `timeout.test.ts` has no test for zero-length max output.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification Results
|
||||||
|
|
||||||
|
### Test Execution (`npm test -- --coverage`)
|
||||||
|
|
||||||
|
```
|
||||||
|
Test Suites: 1 failed, 7 passed, 8 total
|
||||||
|
Tests: 2 failed, 50 passed, 52 total
|
||||||
|
Coverage: 92.3% statements, 91.66% branches, 72.72% functions
|
||||||
|
```
|
||||||
|
|
||||||
|
**Passing suites:**
|
||||||
|
- `contracts.test.ts` — All Zod schema validations pass.
|
||||||
|
- `adapter-factory.test.ts` — Factory correctly returns mock by default.
|
||||||
|
- `group-filtering.test.ts` — Device filtering by group works.
|
||||||
|
- `timeout.test.ts` — Timeout and output limits respected (except edge cases).
|
||||||
|
- `device-status.test.ts` — Status enum handling correct.
|
||||||
|
- `mock-data-loader.test.ts` — JSON fixture loading works.
|
||||||
|
- `integration.test.ts` — Full workflow mocks succeed.
|
||||||
|
|
||||||
|
**Failing tests (non-blocking, expectation issue):**
|
||||||
|
- `mock-adapter.test.ts` — 2 tests fail due to error message mismatch (not logic):
|
||||||
|
- `getDevice` non-existent expects "Resource not found" but receives "Device not found: nonexistent"
|
||||||
|
- `getGroup` non-existent expects "Resource not found" but receives "Group not found: nonexistent"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Build (`npm run build`)
|
||||||
|
|
||||||
|
```
|
||||||
|
node_modules/@types/jest/index.d.ts(14,23): error TS2314
|
||||||
|
node_modules/@types/jest/index.d.ts(683,15): error TS2428
|
||||||
|
src/__tests__/setup.ts(13,15): error TS2428
|
||||||
|
src/__tests__/setup.ts(23,13): error TS7006
|
||||||
|
src/__tests__/setup.ts(30,14): error TS7006
|
||||||
|
src/__tests__/setup.ts(37,14): error TS7006
|
||||||
|
```
|
||||||
|
|
||||||
|
**Status:** Build fails—cannot produce dist artifacts. All errors are in test setup, not source code.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Lint (`npm run lint`)
|
||||||
|
|
||||||
|
```
|
||||||
|
ESLint couldn't find a configuration file. To set up a configuration file for this project, please run:
|
||||||
|
npm init @eslint/config
|
||||||
|
```
|
||||||
|
|
||||||
|
**Status:** Linting entirely skipped—no code style enforcement. Missing `.eslintrc.*` or `eslint.config.js`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Code Coverage
|
||||||
|
|
||||||
|
```
|
||||||
|
----------------------|---------|----------|---------|---------|-------------------
|
||||||
|
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
|
||||||
|
----------------------|---------|----------|---------|---------|-------------------
|
||||||
|
All files | 92.3 | 91.66 | 72.72 | 91.83 |
|
||||||
|
src | 91.83 | 91.66 | 71.87 | 91.3 |
|
||||||
|
adapter.ts | 60 | 87.5 | 44.44 | 60 | 41-65
|
||||||
|
contracts.ts | 100 | 100 | 100 | 100 |
|
||||||
|
index.ts | 100 | 100 | 50 | 100 |
|
||||||
|
mock-adapter.ts | 100 | 90 | 92.3 | 100 | 197
|
||||||
|
src/__tests__ | 100 | 100 | 100 | 100 |
|
||||||
|
```
|
||||||
|
|
||||||
|
**Coverage Gaps:**
|
||||||
|
- `adapter.ts` lines 41–65: Unimplemented real adapter methods.
|
||||||
|
- `mock-adapter.ts` line 197: Edge case in diagnostic output handling (uncovered due to fixed mock data sizes).
|
||||||
|
- `index.ts` line 50: Factory export (uncovered in isolation tests).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scope Creep Assessment
|
||||||
|
|
||||||
|
**Current scope aligns with PROJECT.md Goal 1 (read-only foundation).**
|
||||||
|
|
||||||
|
**Observed scope creep:**
|
||||||
|
- None detected—adapter factory and config correctly default to `'mock'`.
|
||||||
|
- `example-config-real.json` suggests real adapter is WIP, not production-ready.
|
||||||
|
|
||||||
|
**Not yet in scope (per TODO.md):**
|
||||||
|
- Diagnostics beyond mock data.
|
||||||
|
- State-changing actions (reboot, service restart).
|
||||||
|
- Confirmation flows or dry-run.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TLS and Auth Assumptions (Per Research)
|
||||||
|
|
||||||
|
| Requirement | Current Implementation | Research Finding |
|
||||||
|
|-------------|------------------------|------------------|
|
||||||
|
| TLS certificate validation | Unknown (no actual connection) | Must be enabled; no `rejectUnauthorized: false` |
|
||||||
|
| WebSocket endpoint | Not implemented | `wss://host:port/control.ashx` |
|
||||||
|
| Auth header | Not implemented | `x-meshauth: base64(username,password,2fa?)` |
|
||||||
|
| Login key support | Not implemented | High sensitivity—avoid unless explicitly chosen |
|
||||||
|
|
||||||
|
**Conclusion:** The real adapter is currently a stub that will fail or expose credentials if used with live MeshCentral.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Test Failure Classification
|
||||||
|
|
||||||
|
| Test | Failure Type | Fix Required |
|
||||||
|
|------|--------------|--------------|
|
||||||
|
| `mock-adapter.test.ts:56` | Expectation mismatch (error message) | Update test expectation |
|
||||||
|
| `mock-adapter.test.ts:86` | Expectation mismatch (error message) | Update test expectation |
|
||||||
|
| TypeScript build errors | Type definition conflict | Fix `setup.ts` types |
|
||||||
|
| ESLint failure | Missing config | Add `.eslintrc.*` |
|
||||||
|
|
||||||
|
**Note:** No test failures indicate logic defects in core functionality.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recommendations
|
||||||
|
|
||||||
|
### Immediate (Before Live Integration)
|
||||||
|
|
||||||
|
1. **Fix TypeScript errors in `src/__tests__/setup.ts`** to enable build.
|
||||||
|
2. **Add ESLint configuration** and enforce linting in CI.
|
||||||
|
3. **Fix test expectations** to align with actual error messages (or standardize messages).
|
||||||
|
4. **Implement `MeshCentralRealAdapter`** with:
|
||||||
|
- Secure TLS (enabled validation).
|
||||||
|
- WebSocket connection to `/control.ashx`.
|
||||||
|
- `x-meshauth` header authentication.
|
||||||
|
- Configurable `username`, `password`, or explicit opt-in for login key.
|
||||||
|
5. **Add audit logging** with structured JSON output.
|
||||||
|
|
||||||
|
### Short-Term (Before Production)
|
||||||
|
|
||||||
|
6. Implement device/group allowlists.
|
||||||
|
7. Add output sanitization for diagnostics.
|
||||||
|
8. Define and enforce diagnostic policies.
|
||||||
|
9. Add version compatibility checks.
|
||||||
|
10. Implement retry logic with backoff.
|
||||||
|
|
||||||
|
### Medium-Term (After Security Review)
|
||||||
|
|
||||||
|
11. Add confirmation flow for reversible actions.
|
||||||
|
12. Implement dry-run support.
|
||||||
|
13. Add idempotency and duplicate-execution protection.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The implementation is a **well-structured mock-based scaffold** suitable for local development and testing, but it is not production-ready. The real adapter is **unimplemented** and contains no security controls beyond basic config structure.
|
||||||
|
|
||||||
|
**Do not proceed with live MeshCentral integration until:**
|
||||||
|
- The real adapter is implemented per security requirements.
|
||||||
|
- All build/lint/test failures are resolved.
|
||||||
|
- An independent security review confirms TLS, auth, and logging.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendix A: File Inventory
|
||||||
|
|
||||||
|
| File | Status | Notes |
|
||||||
|
|------|--------|-------|
|
||||||
|
| `src/index.ts` | ✅ Clean | Exports adapter factory and contracts |
|
||||||
|
| `src/adapter.ts` | ⚠️ Stub | Real adapter unimplemented; healthCheck uses wrong endpoint |
|
||||||
|
| `src/mock-adapter.ts` | ✅ Complete | Full mock with test fixtures |
|
||||||
|
| `src/contracts.ts` | ✅ Complete | Zod schemas, enums, types |
|
||||||
|
| `src/__tests__/adapter-factory.test.ts` | ✅ Pass | Factory correctly returns mock by default |
|
||||||
|
| `src/__tests__/contracts.test.ts` | ✅ Pass | All Zod schema validations pass |
|
||||||
|
| `src/__tests__/device-status.test.ts` | ✅ Pass | Status enum handling correct |
|
||||||
|
| `src/__tests__/group-filtering.test.ts` | ✅ Pass | Device filtering by group works |
|
||||||
|
| `src/__tests__/integration.test.ts` | ✅ Pass | Full workflow mocks succeed |
|
||||||
|
| `src/__tests__/mock-adapter.test.ts` | ⚠️ 2/6 fail | Expectation mismatch on error messages |
|
||||||
|
| `src/__tests__/mock-data-loader.test.ts` | ✅ Pass | JSON fixture loading works |
|
||||||
|
| `src/__tests__/setup.ts` | ❌ Broken | TypeScript errors block build and coverage |
|
||||||
|
| `src/__tests__/timeout.test.ts` | ✅ Pass | Timeout and output limits respected |
|
||||||
|
|
||||||
|
**Test Summary:**
|
||||||
|
- 50 tests pass (96.2%)
|
||||||
|
- 2 tests fail due to error message expectation mismatch
|
||||||
|
- Build fails due to TypeScript type conflicts in test setup
|
||||||
|
- Linting skipped due to missing ESLint configuration
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*End of Review Report*
|
||||||
+582
@@ -0,0 +1,582 @@
|
|||||||
|
# MeshCentral ↔ OpenClaw Bridge — Story So Far
|
||||||
|
|
||||||
|
**Project:** `meshcentral-openclaw-bridge`
|
||||||
|
**Project path:** `/home/ledadmin/projects/meshcentral-openclaw-bridge`
|
||||||
|
**Owner:** Rob
|
||||||
|
**Project manager:** Clawdia
|
||||||
|
**Write-up date:** 2026-08-26
|
||||||
|
**Current status:** **Paused / blocked after three failed, bounded read-only live probes**
|
||||||
|
|
||||||
|
> This document is a narrative history of the work completed so far. It deliberately excludes the MeshCentral password, authentication headers, session tokens, and raw server-provided close/error text. The project credential remains outside the repository in a protected file.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. The original goal
|
||||||
|
|
||||||
|
The project began as an effort to give OpenClaw a carefully controlled interface to Rob's MeshCentral deployment. The intended long-term capability is for Rob to ask OpenClaw questions such as:
|
||||||
|
|
||||||
|
- Which managed systems are offline?
|
||||||
|
- What operating system, uptime, and agent status does a host report?
|
||||||
|
- Can a narrowly defined diagnostic check be run against one approved system?
|
||||||
|
- Later, can an explicitly confirmed and auditable remediation action be performed?
|
||||||
|
|
||||||
|
The important design choice from the beginning was to treat this as a remote-management control plane, not as a convenience API. MeshCentral can ultimately expose shell access, file transfer, power operations, and other highly privileged actions, so the bridge must not become an unrestricted command channel.
|
||||||
|
|
||||||
|
The delivery plan was split into explicit phases:
|
||||||
|
|
||||||
|
1. Discovery
|
||||||
|
2. Architecture and security design
|
||||||
|
3. Read-only inventory/status MVP
|
||||||
|
4. Allowlisted diagnostics
|
||||||
|
5. Confirmation-gated reversible actions
|
||||||
|
6. Hardening, deployment, rollback, and operational handoff
|
||||||
|
|
||||||
|
Only the first three phases, plus local hardening and compatibility testing, have been pursued. Diagnostics remain simulated/mock-only, and no remote command or state-changing operation has been implemented or used.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Initial scope and safety boundaries
|
||||||
|
|
||||||
|
The initial milestone was deliberately narrowed to:
|
||||||
|
|
||||||
|
- MeshCentral server version/health
|
||||||
|
- Device-group listing
|
||||||
|
- Device inventory
|
||||||
|
- Online/offline state
|
||||||
|
- Safe device metadata
|
||||||
|
- Structured results suitable for an OpenClaw integration
|
||||||
|
|
||||||
|
The initial milestone explicitly excluded:
|
||||||
|
|
||||||
|
- Arbitrary shell or command execution
|
||||||
|
- Remote diagnostics that execute commands
|
||||||
|
- File transfer
|
||||||
|
- Router/tunnel operations
|
||||||
|
- Reboots, shutdowns, or service changes
|
||||||
|
- User/group administration
|
||||||
|
- Autonomous remediation
|
||||||
|
- Fleet-wide operations
|
||||||
|
- Public exposure of the bridge
|
||||||
|
- Access to the production Proxmox cluster through this project
|
||||||
|
|
||||||
|
The first architecture decision, recorded as ADR-0001, was therefore to begin read-only. That allowed the project to validate connectivity, authentication, data mapping, logging, failure handling, and OpenClaw-facing contracts without changing an endpoint.
|
||||||
|
|
||||||
|
A second decision was to prefer a local typed bridge over browser automation. Browser automation was retained as a possible fallback for discovery or occasional operations, but not as the primary integration architecture. A local adapter is easier to constrain, unit-test, audit, and maintain than a collection of UI selectors and browser sessions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Discovery and integration research
|
||||||
|
|
||||||
|
### 3.1 MeshCentral deployment facts
|
||||||
|
|
||||||
|
The project documented the known deployment as follows:
|
||||||
|
|
||||||
|
- Public/reverse-proxy name: `mesh.ledrew.me`
|
||||||
|
- Internal MeshCentral address: `10.10.10.177:80`
|
||||||
|
- Reported MeshCentral version: `1.2.5`
|
||||||
|
- Location: LXC on PVE2
|
||||||
|
- Installation method: Proxmox Community Scripts MeshCentral installer
|
||||||
|
- Installation path: `/opt/meshcentral`
|
||||||
|
- Data path: `/opt/meshcentral/meshcentral-data`
|
||||||
|
- Service: `meshcentral.service`
|
||||||
|
- Approved test device: `PVE3`
|
||||||
|
- Approved MeshCentral group: `Servers`
|
||||||
|
- Dedicated integration account: `sa_clawdia`
|
||||||
|
- Intended external control endpoint: `wss://mesh.ledrew.me/control.ashx`
|
||||||
|
|
||||||
|
The first live target was restricted to PVE3. PVE1 and PVE2 production infrastructure were explicitly kept out of scope.
|
||||||
|
|
||||||
|
### 3.2 Options considered
|
||||||
|
|
||||||
|
The research looked at several possible integration surfaces:
|
||||||
|
|
||||||
|
1. **Official `meshctrl.js` control client** — selected as the practical starting point.
|
||||||
|
2. **MeshCentral server internals or an in-process module** — rejected for the first version because it would couple the bridge to private implementation details, deployment paths, process state, and upgrade behavior.
|
||||||
|
3. **Browser automation** — not selected as the primary path because it is more fragile and difficult to constrain.
|
||||||
|
4. **Third-party MCP or MeshCentral adapters** — no clearly mature, maintained general-purpose adapter was found. A related automation-template project was noted, but it was not treated as a trusted dependency.
|
||||||
|
|
||||||
|
The selected approach was a separate, typed local adapter that implements only a small read-only subset of MeshCentral's control-channel protocol. The raw protocol would remain behind the adapter boundary rather than being exposed directly as an OpenClaw tool API.
|
||||||
|
|
||||||
|
### 3.3 Protocol and security observations from research
|
||||||
|
|
||||||
|
The official MeshCentral control client uses a WebSocket connection to `/control.ashx` and exchanges JSON actions and responses. Relevant read-only actions include:
|
||||||
|
|
||||||
|
- `serverversion`
|
||||||
|
- `meshes`
|
||||||
|
- `nodes`
|
||||||
|
- `deviceinfo`
|
||||||
|
|
||||||
|
The official client also supports more powerful operations, but the project intentionally did not pass those through.
|
||||||
|
|
||||||
|
Research found two especially important security points:
|
||||||
|
|
||||||
|
- MeshCentral's control protocol is an implementation-level contract, not a separately versioned stable REST API. Version pinning, fixtures, schema checks, and live compatibility verification are therefore necessary.
|
||||||
|
- The upstream client source was observed to disable TLS certificate verification. The bridge intentionally did **not** copy that behavior. The bridge requires certificate validation and supports an explicit CA configuration path instead.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. The first implementation iteration: mock-backed scaffold
|
||||||
|
|
||||||
|
The first code iteration created a local TypeScript project under `implementation/`. It established the bridge boundary without requiring a live MeshCentral connection.
|
||||||
|
|
||||||
|
### 4.1 Core structure
|
||||||
|
|
||||||
|
The implementation introduced:
|
||||||
|
|
||||||
|
- TypeScript source and build configuration
|
||||||
|
- Zod-backed typed contracts
|
||||||
|
- A `MeshCentralAdapter` interface
|
||||||
|
- A mock adapter for offline development
|
||||||
|
- Adapter factory logic
|
||||||
|
- Structured bridge errors and error codes
|
||||||
|
- Example configurations
|
||||||
|
- Jest tests and coverage output
|
||||||
|
- Build and lint scripts
|
||||||
|
|
||||||
|
The mock adapter models device groups, devices, status, metadata, and diagnostic results. The mock data includes online and offline devices, group filtering, device lookups, and output truncation behavior.
|
||||||
|
|
||||||
|
### 4.2 What the mock path proved
|
||||||
|
|
||||||
|
The mock path established that the intended OpenClaw-facing abstraction could support:
|
||||||
|
|
||||||
|
- Listing devices
|
||||||
|
- Filtering by group ID
|
||||||
|
- Getting one device
|
||||||
|
- Listing groups
|
||||||
|
- Getting one group
|
||||||
|
- Returning online/offline/unknown state
|
||||||
|
- Returning safe metadata such as OS, uptime, IPs, and agent version
|
||||||
|
- Running simulated diagnostic checks
|
||||||
|
- Reporting health
|
||||||
|
- Returning structured errors for missing resources
|
||||||
|
- Enforcing output limits and truncation metadata
|
||||||
|
|
||||||
|
At this stage, the real adapter was either absent or only a scaffold. This is the state described by the earliest independent review: the mock path was functional, while the live path was not yet suitable for use.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. The first independent review and its findings
|
||||||
|
|
||||||
|
An independent review was performed against the early implementation. At that point the local suite was already passing, but the review correctly identified that passing mock tests did not make the real control path safe.
|
||||||
|
|
||||||
|
The early review reported:
|
||||||
|
|
||||||
|
- The real adapter was not yet fully implemented.
|
||||||
|
- Credential validation and sanitization were insufficient.
|
||||||
|
- Response schema validation was missing.
|
||||||
|
- Error paths could potentially expose too much detail.
|
||||||
|
- TLS behavior needed to be explicit and configurable.
|
||||||
|
- There was no request rate limiting or bounded concurrency.
|
||||||
|
- Device/group allowlist validation needed strengthening.
|
||||||
|
- Structured audit logging was incomplete.
|
||||||
|
- Separate connection/request timeouts and reconnect behavior were desirable future improvements.
|
||||||
|
|
||||||
|
The early review's local test snapshot was 52 tests across 8 suites, with build and lint passing. Its conclusion was explicitly **do not enable live testing** until the high-severity findings were addressed.
|
||||||
|
|
||||||
|
This review became the basis for the hardening pass rather than being discarded. Later documentation records which findings were fixed, which were deferred, and what residual risks remained.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Hardening iteration: making the local MVP defensible
|
||||||
|
|
||||||
|
The next major iteration turned the scaffold into a real, but still tightly constrained, MeshCentral control-channel adapter.
|
||||||
|
|
||||||
|
### 6.1 Real MeshCentral client
|
||||||
|
|
||||||
|
`implementation/src/meshctrl-client.ts` was developed as a WebSocket client for MeshCentral's `/control.ashx` endpoint. It added:
|
||||||
|
|
||||||
|
- WebSocket URL construction
|
||||||
|
- Authentication header creation
|
||||||
|
- Connection and request timeouts
|
||||||
|
- Request/response correlation
|
||||||
|
- Bounded retry behavior
|
||||||
|
- Clean disconnect and cleanup
|
||||||
|
- Response parsing
|
||||||
|
- Protocol and action validation
|
||||||
|
- Explicit TLS certificate validation
|
||||||
|
- Optional custom CA support
|
||||||
|
|
||||||
|
The client was designed to fail closed when the session, response shape, action, or connection state was ambiguous.
|
||||||
|
|
||||||
|
### 6.2 Credential handling
|
||||||
|
|
||||||
|
Credential handling was hardened so that:
|
||||||
|
|
||||||
|
- Credentials are validated before encoding or storage.
|
||||||
|
- Invalid usernames, passwords, and optional TOTP values are rejected.
|
||||||
|
- User-facing configuration failures remain generic.
|
||||||
|
- Credential metadata is summarized rather than printed.
|
||||||
|
- Passwords, TOTP values, authentication headers, cookies, and tokens are not intentionally logged.
|
||||||
|
- The live runner reads the password from a protected runtime file rather than accepting it as a command-line argument.
|
||||||
|
|
||||||
|
The actual credential is not part of this repository or this write-up.
|
||||||
|
|
||||||
|
### 6.3 TLS handling
|
||||||
|
|
||||||
|
The bridge explicitly sets certificate validation on the WebSocket connection. It does not inherit the upstream client's certificate-verification bypass. A private CA bundle can be configured if needed, but disabling validation is prohibited.
|
||||||
|
|
||||||
|
This distinction matters because the connection is a management control path. A successful WebSocket connection is not enough if the peer identity has not been verified.
|
||||||
|
|
||||||
|
### 6.4 Protocol and response validation
|
||||||
|
|
||||||
|
The client added several defensive checks:
|
||||||
|
|
||||||
|
- Maximum response size of 1 MB
|
||||||
|
- JSON parsing and protocol-envelope validation
|
||||||
|
- Action-specific response schemas using Zod
|
||||||
|
- Request/response action matching
|
||||||
|
- Rejection of malformed or unexpected responses
|
||||||
|
- Generic MeshCentral request errors instead of passing raw server error text through the bridge
|
||||||
|
|
||||||
|
These controls address the early review's concern that a syntactically valid WebSocket message should not automatically be trusted as a valid response.
|
||||||
|
|
||||||
|
### 6.5 Target protection
|
||||||
|
|
||||||
|
The real adapter added device and group allowlists. It filters inventory results and checks requested targets against the configured allowlist.
|
||||||
|
|
||||||
|
The intended live configuration is single-target:
|
||||||
|
|
||||||
|
- MeshCentral group: `Servers`
|
||||||
|
- Device: `PVE3`
|
||||||
|
- No PVE1/PVE2 access
|
||||||
|
|
||||||
|
The adapter also validates allowlist configuration rather than treating arbitrary IDs as trusted input.
|
||||||
|
|
||||||
|
### 6.6 Rate limiting and concurrency
|
||||||
|
|
||||||
|
The client added two protective controls:
|
||||||
|
|
||||||
|
- A token-bucket rate limiter for outbound requests
|
||||||
|
- A concurrency limiter/semaphore for simultaneous requests
|
||||||
|
|
||||||
|
The safe default for concurrent requests is 5. Configuration values are bounded to prevent accidentally setting unreasonable limits. These controls are safety guardrails; they are not considered a substitute for proper capacity testing.
|
||||||
|
|
||||||
|
### 6.7 Logging and audit controls
|
||||||
|
|
||||||
|
Structured logging and audit utilities were added or expanded. The implementation records security-relevant events such as connection attempts, authentication outcomes, requests, target decisions, results, and failures without intentionally including secrets.
|
||||||
|
|
||||||
|
Redaction handles:
|
||||||
|
|
||||||
|
- Known secret keys
|
||||||
|
- Password and token fields
|
||||||
|
- Authentication headers
|
||||||
|
- Token-like values
|
||||||
|
- Base64-looking secret material
|
||||||
|
- Hex-looking secret material
|
||||||
|
- Nested objects and arrays
|
||||||
|
|
||||||
|
A later logger cleanup also removed direct audit output from the client/rate-limiter paths in favor of the existing logger abstraction. This preserved redaction and made the lint gate clean.
|
||||||
|
|
||||||
|
### 6.8 Diagnostics remain mock-only
|
||||||
|
|
||||||
|
The adapter interface still contains diagnostic support for the mock implementation, but the real path does not execute commands. The live runner was specifically tested to ensure it contains only the approved read-only actions and does not expose a general-purpose command or diagnostic action.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Hardening verification milestones
|
||||||
|
|
||||||
|
The test suite grew as the implementation gained controls.
|
||||||
|
|
||||||
|
The recorded milestones were approximately:
|
||||||
|
|
||||||
|
1. **Early scaffold:** 52 tests across 8 suites; build and lint passed.
|
||||||
|
2. **Post-hardening checkpoint:** 56 tests; build, lint, and `tsc --noEmit` passed.
|
||||||
|
3. **Expanded local MVP:** 90 tests across 11 suites; build passed; lint passed with no warnings.
|
||||||
|
4. **Secure live-test runner:** 91 tests; build passed; lint passed.
|
||||||
|
5. **Final runner/diagnostic and cleanup changes:** 12 suites and 91 tests; build passed; lint passed with no warnings.
|
||||||
|
|
||||||
|
The project documentation also records a 90/90 local verification result immediately before the final live-test preparation. The small count differences reflect tests added during subsequent runner and cleanup work, not a reduction in coverage.
|
||||||
|
|
||||||
|
The test categories include:
|
||||||
|
|
||||||
|
- Contract/schema validation
|
||||||
|
- Mock adapter behavior
|
||||||
|
- Adapter factory behavior
|
||||||
|
- Device status and offline handling
|
||||||
|
- Group filtering
|
||||||
|
- Full mock integration workflows
|
||||||
|
- Timeout and output limits
|
||||||
|
- Credential validation and redaction
|
||||||
|
- Protocol response parsing and size limits
|
||||||
|
- Action-specific response validation
|
||||||
|
- Rate limiting
|
||||||
|
- Concurrency limiting
|
||||||
|
- Live-runner scope safety
|
||||||
|
- MeshCtrl client behavior
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Protocol compatibility correction
|
||||||
|
|
||||||
|
The first live-compatible implementation was based on an incorrect assumption about parts of MeshCentral's wire format. The exact deployed-version-pinned `meshctrl.js` source was then compared against the bridge.
|
||||||
|
|
||||||
|
The reference was MeshCentral `1.2.5`, associated with commit:
|
||||||
|
|
||||||
|
`b09b1d60328de8e2d2f7387561ed51c64011c82a`
|
||||||
|
|
||||||
|
The comparison produced `PROTOCOL-COMPARISON.md` and identified the following corrections.
|
||||||
|
|
||||||
|
### 8.1 Authentication header format
|
||||||
|
|
||||||
|
The earlier bridge assumption treated the credentials as one Base64-encoded combined string. The official client uses comma-separated Base64 fields for the username and password, with an optional third Base64 field for a TOTP token.
|
||||||
|
|
||||||
|
The bridge was corrected to match the official wire format while retaining its own validation and redaction safeguards.
|
||||||
|
|
||||||
|
### 8.2 Response correlation
|
||||||
|
|
||||||
|
The earlier bridge used a numeric request ID model. The official control client uses a `responseid` value, with the response echoing that value.
|
||||||
|
|
||||||
|
The bridge was changed to generate unique `responseid` values and correlate responses using the official field.
|
||||||
|
|
||||||
|
### 8.3 Server-version response shape
|
||||||
|
|
||||||
|
The bridge initially expected fields that did not match the official response shape. The compatibility work updated validation to accept the protocol envelope used by MeshCentral, including the expected result/tags-style fields.
|
||||||
|
|
||||||
|
### 8.4 Handshake behavior
|
||||||
|
|
||||||
|
The comparison found no special application-level handshake message required before the first request. The request is sent after the WebSocket `open` event.
|
||||||
|
|
||||||
|
The bridge therefore did not add an unnecessary extra handshake. It retained the safer TLS behavior rather than copying the official client's certificate-verification weakness.
|
||||||
|
|
||||||
|
### 8.5 Why this correction mattered
|
||||||
|
|
||||||
|
The initial implementation could establish the WebSocket upgrade but was not fully wire-compatible for request/response correlation. The protocol correction was covered by local tests before the next live attempt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Live-test runner and authorization
|
||||||
|
|
||||||
|
A fixed-scope live runner was added as `implementation/src/live-readonly-test.ts`, exposed through:
|
||||||
|
|
||||||
|
```text
|
||||||
|
npm run live-test
|
||||||
|
```
|
||||||
|
|
||||||
|
The runner was intentionally designed not to accept arbitrary target, action, or credential command-line arguments. It contains fixed constants for:
|
||||||
|
|
||||||
|
- MeshCentral URL
|
||||||
|
- Integration username
|
||||||
|
- Approved group name
|
||||||
|
- Approved device name
|
||||||
|
- Protected credential-file location
|
||||||
|
|
||||||
|
Its operation sequence is:
|
||||||
|
|
||||||
|
1. Read the protected password file and verify restrictive permissions.
|
||||||
|
2. Connect using the real MeshCentral client.
|
||||||
|
3. Request the server version.
|
||||||
|
4. Locate the approved `Servers` group.
|
||||||
|
5. Request nodes for that group.
|
||||||
|
6. Resolve the approved `PVE3` device.
|
||||||
|
7. Request device metadata for that device only.
|
||||||
|
8. Validate scope and response shapes.
|
||||||
|
9. Disconnect cleanly.
|
||||||
|
|
||||||
|
The runner's safety test checks that it references only:
|
||||||
|
|
||||||
|
- `serverversion`
|
||||||
|
- `meshes`
|
||||||
|
- `nodes`
|
||||||
|
- `deviceinfo`
|
||||||
|
|
||||||
|
It also checks that the source does not expose `runcommand`, general diagnostics, or `process.argv` handling.
|
||||||
|
|
||||||
|
Rob authorized project-level read-only MeshCentral access on 2026-08-26. That authorization covers the documented compatibility probe only. It does not authorize commands, diagnostics, power operations, file transfer, administration, state changes, or any target other than PVE3.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Live testing: what happened
|
||||||
|
|
||||||
|
### 10.1 What succeeded
|
||||||
|
|
||||||
|
The bounded live probe demonstrated that:
|
||||||
|
|
||||||
|
- The external WebSocket endpoint was reachable.
|
||||||
|
- TLS negotiation completed.
|
||||||
|
- Certificate validation succeeded.
|
||||||
|
- The WebSocket upgrade/setup reached the MeshCentral service.
|
||||||
|
|
||||||
|
This ruled out a simple DNS, network, certificate, or basic WebSocket-upgrade failure.
|
||||||
|
|
||||||
|
### 10.2 What failed
|
||||||
|
|
||||||
|
The server closed the control session before the first `serverversion` request could complete. The bridge's health check returned false. A direct client diagnostic showed the socket opening and then becoming unusable after the server-side close.
|
||||||
|
|
||||||
|
The failure was classified at the safe `serverversion` stage as a protocol-or-connection failure. The exact server-provided close values were intentionally not preserved in project notes because server text can contain sensitive operational details.
|
||||||
|
|
||||||
|
### 10.3 What did not happen
|
||||||
|
|
||||||
|
No successful live operation progressed beyond the first server-version stage. Specifically, the live attempts did **not** complete:
|
||||||
|
|
||||||
|
- Group enumeration
|
||||||
|
- Device inventory
|
||||||
|
- PVE3 metadata retrieval
|
||||||
|
- Diagnostics
|
||||||
|
- Commands
|
||||||
|
- Shell access
|
||||||
|
- File transfer
|
||||||
|
- Power operations
|
||||||
|
- Administrative changes
|
||||||
|
- Any state change
|
||||||
|
- Any access to PVE1 or PVE2
|
||||||
|
|
||||||
|
No password, auth header, cookie, session token, or raw server error text was written to logs or project files.
|
||||||
|
|
||||||
|
### 10.4 Three-attempt stop rule
|
||||||
|
|
||||||
|
The live probe failed three consecutive times at the same safe stage. The project had a configured maximum of three consecutive live failures, so live testing stopped automatically at that point.
|
||||||
|
|
||||||
|
The failure count must not be reset simply to retry the same hypothesis. A future attempt should only occur after the protocol/connection hypothesis has changed and the retry decision has been explicitly reviewed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. MeshCentral-side evidence collected
|
||||||
|
|
||||||
|
The project recorded the following facts about the MeshCentral LXC and service:
|
||||||
|
|
||||||
|
- `meshcentral.service` was active.
|
||||||
|
- The main process was the expected Node.js MeshCentral process under `/opt/meshcentral`.
|
||||||
|
- The service was running in production mode.
|
||||||
|
- No debug flags were present in the service start command.
|
||||||
|
- MeshCentral data files were present under the expected data directory.
|
||||||
|
- A normal log file was not found through the provided search.
|
||||||
|
- `journalctl` around the test window did not provide useful service entries.
|
||||||
|
|
||||||
|
No MeshCentral service configuration was changed, and debug logging was not enabled. As a result, the server currently does not provide enough operational detail to identify exactly why the control channel closes before `serverversion`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Worker/watchdog orchestration attempt
|
||||||
|
|
||||||
|
Because this was being treated as a multi-step supervised project, a durable progress/watchdog arrangement was attempted.
|
||||||
|
|
||||||
|
The project added:
|
||||||
|
|
||||||
|
- `PROJECT-PROGRESS.json` as persisted authoritative state
|
||||||
|
- `worker/run-worker.js`
|
||||||
|
- `worker/worker.log`
|
||||||
|
- A progress/watchdog cron arrangement
|
||||||
|
|
||||||
|
The worker was intended to run local verification, execute the bounded probe, checkpoint status, and stop at the configured live-failure limit.
|
||||||
|
|
||||||
|
There were problems with observability and orchestration:
|
||||||
|
|
||||||
|
- One-shot subagent workers exited before completing all intended checkpoints.
|
||||||
|
- A detached Node worker did execute verification and live probes, but child output was buffered and checkpoint logging was incomplete, leaving `worker.log` empty.
|
||||||
|
- Watchdog cron setup had intermittent timeouts.
|
||||||
|
- The persisted JSON state was therefore treated as more authoritative than the worker log.
|
||||||
|
|
||||||
|
At the pause point, the progress state recorded three live failures, the `serverversion` blocker, and the stop-rule decision. The progress cron was disabled at Rob's request and preserved rather than deleted.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Documentation and review artifacts created
|
||||||
|
|
||||||
|
The project now contains the following key records:
|
||||||
|
|
||||||
|
- `README.md` — project vision, workflow, non-goals, and documentation map
|
||||||
|
- `PROJECT.md` — goals, phases, scope boundaries, and multi-agent workflow
|
||||||
|
- `SECURITY.md` — threat model, security requirements, and action classes
|
||||||
|
- `DECISIONS.md` — architecture decisions
|
||||||
|
- `TODO.md` — milestone and live-test checklist
|
||||||
|
- `research/INTEGRATION-RESEARCH.md` — integration-surface research and protocol/security findings
|
||||||
|
- `review/REVIEW.md` — early independent review of the under-hardened implementation
|
||||||
|
- `review/LIVE-ADAPTER-REVIEW.md` — independent live-adapter security review
|
||||||
|
- `review/FINAL-HARDENING-REVIEW.md` — reconciliation of early findings against current source
|
||||||
|
- `PROTOCOL-COMPARISON.md` — exact MeshCentral 1.2.5 protocol comparison
|
||||||
|
- `DEPLOYMENT.md` — deployment facts, secret handling, live gates, and rollback
|
||||||
|
- `LIVE-TEST-PROCEDURE.md` — fixed-scope read-only test procedure and stop conditions
|
||||||
|
- `RESUME-HANDOFF.md` — resume instructions from the earlier checkpoint
|
||||||
|
- `PROJECT-STATUS-2026-08-25.md` — detailed project status snapshot
|
||||||
|
- `SESSION-CHECKPOINT-2026-08-26.md` — final pause state and worker findings
|
||||||
|
- `PROJECT-PROGRESS.json` — current machine-readable progress state
|
||||||
|
- `implementation/README.md` — implementation usage, layout, and scope
|
||||||
|
- `story-so-far.md` — this historical narrative
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Current implementation state
|
||||||
|
|
||||||
|
### Working locally
|
||||||
|
|
||||||
|
- Typed contracts and Zod validation
|
||||||
|
- Mock adapter
|
||||||
|
- Real MeshCentral WebSocket client
|
||||||
|
- Real read-only adapter methods
|
||||||
|
- Credential validation
|
||||||
|
- TLS certificate validation
|
||||||
|
- Optional custom CA support
|
||||||
|
- Protocol and response validation
|
||||||
|
- Response-size limits
|
||||||
|
- Request/response correlation using `responseid`
|
||||||
|
- Device/group allowlists
|
||||||
|
- Timeout and bounded retry behavior
|
||||||
|
- Token-bucket rate limiting
|
||||||
|
- Bounded concurrent requests
|
||||||
|
- Structured logging and redaction
|
||||||
|
- Audit event generation
|
||||||
|
- Fixed-scope live runner
|
||||||
|
- Automated tests/build/lint
|
||||||
|
|
||||||
|
### Deliberately not implemented or not approved
|
||||||
|
|
||||||
|
- Real diagnostics
|
||||||
|
- Remote command execution
|
||||||
|
- Shell access
|
||||||
|
- File transfer
|
||||||
|
- Power operations
|
||||||
|
- Reboots/shutdowns
|
||||||
|
- Service changes
|
||||||
|
- User/group administration
|
||||||
|
- Autonomous actions
|
||||||
|
- Production-cluster targeting
|
||||||
|
- Public bridge exposure
|
||||||
|
- Automatic reconnect/session renewal for production fleet use
|
||||||
|
|
||||||
|
The absence of automatic reconnect is currently safer for the first test because a dropped session fails instead of autonomously replaying requests. Separate connection/request timeout design and production-grade reconnect behavior remain deferred items.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Current status at pause
|
||||||
|
|
||||||
|
The local code is verification-passing, but live MeshCentral compatibility is unresolved.
|
||||||
|
|
||||||
|
The authoritative current state is:
|
||||||
|
|
||||||
|
- **Project:** `meshcentral-openclaw-bridge`
|
||||||
|
- **Status:** blocked / paused
|
||||||
|
- **Local tests:** passing at the latest recorded checkpoint
|
||||||
|
- **Build:** passing
|
||||||
|
- **Lint:** passing with no warnings
|
||||||
|
- **Live failures:** 3 consecutive
|
||||||
|
- **Failure stage:** `serverversion`
|
||||||
|
- **Failure category:** protocol-or-connection
|
||||||
|
- **Live testing:** stopped by the configured failure-limit rule
|
||||||
|
- **Diagnostics:** mock-only
|
||||||
|
- **Remote commands/state changes:** not implemented and prohibited
|
||||||
|
- **Approved live target:** PVE3 only
|
||||||
|
- **Production PVE1/PVE2:** off-limits
|
||||||
|
- **Progress cron:** disabled at Rob's request
|
||||||
|
- **Worker:** no active worker at the checkpoint
|
||||||
|
|
||||||
|
The project is not ready to claim a successful live integration. It is accurate to call it a hardened local read-only MVP with an unresolved MeshCentral 1.2.5 control-channel compatibility problem.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 16. What needs to happen next
|
||||||
|
|
||||||
|
When Rob explicitly asks to resume, the next work should be:
|
||||||
|
|
||||||
|
1. Review this document, `SESSION-CHECKPOINT-2026-08-26.md`, `PROJECT-PROGRESS.json`, `RESUME-HANDOFF.md`, `PROTOCOL-COMPARISON.md`, `review/FINAL-HARDENING-REVIEW.md`, and `LIVE-TEST-PROCEDURE.md`.
|
||||||
|
2. Inspect the exact sanitized close/error behavior without exposing raw sensitive server text.
|
||||||
|
3. Compare the deployed MeshCentral 1.2.5 server behavior and bundled client more deeply, especially authentication acceptance and the first control-channel request.
|
||||||
|
4. Repair the worker/checkpoint logging if durable background execution is needed again.
|
||||||
|
5. Add or update local protocol fixtures for the revised hypothesis.
|
||||||
|
6. Run the full local tests, TypeScript build, and lint.
|
||||||
|
7. Do not reset the three-failure count or retry the live probe until the hypothesis has materially changed and the retry policy is reviewed.
|
||||||
|
8. If a revised live test is authorized, keep it limited to `serverversion`, `meshes`, `nodes`, and `deviceinfo` for PVE3 only.
|
||||||
|
9. Do not add diagnostics, commands, or state-changing actions as a way to troubleshoot the current connection problem.
|
||||||
|
|
||||||
|
The central unresolved question is: **why does MeshCentral accept the TLS/WebSocket setup but close the control session before completing the first `serverversion` request?**
|
||||||
|
|
||||||
|
That is where the project currently stands.
|
||||||
@@ -0,0 +1,123 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
/*
|
||||||
|
* Durable, single-instance project worker. It executes bounded checkpoints and
|
||||||
|
* persists state. It never sends non-read-only MeshCentral operations.
|
||||||
|
*/
|
||||||
|
const fs = require('node:fs');
|
||||||
|
const path = require('node:path');
|
||||||
|
const { spawn } = require('node:child_process');
|
||||||
|
|
||||||
|
const root = path.resolve(__dirname, '..');
|
||||||
|
const statePath = path.join(root, 'PROJECT-PROGRESS.json');
|
||||||
|
const lockPath = path.join(root, '.worker.lock');
|
||||||
|
const implementation = path.join(root, 'implementation');
|
||||||
|
const maxLiveFailures = 3;
|
||||||
|
const intervalMs = 15 * 60 * 1000;
|
||||||
|
|
||||||
|
let lock;
|
||||||
|
try {
|
||||||
|
lock = fs.openSync(lockPath, 'wx');
|
||||||
|
fs.writeFileSync(lock, `${process.pid}\n`, 'utf8');
|
||||||
|
} catch {
|
||||||
|
process.stderr.write('worker already running or lock unavailable\n');
|
||||||
|
process.exit(2);
|
||||||
|
}
|
||||||
|
|
||||||
|
function readState() {
|
||||||
|
return JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
||||||
|
}
|
||||||
|
function writeState(state) {
|
||||||
|
state.worker = state.worker || {};
|
||||||
|
state.worker.pid = process.pid;
|
||||||
|
state.worker.lastActivityAt = new Date().toISOString();
|
||||||
|
fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
|
||||||
|
}
|
||||||
|
function run(command, args) {
|
||||||
|
return new Promise((resolve) => {
|
||||||
|
const child = spawn(command, args, { cwd: implementation, stdio: ['ignore', 'pipe', 'pipe'] });
|
||||||
|
let output = '';
|
||||||
|
child.stdout.on('data', (chunk) => { output += chunk.toString(); });
|
||||||
|
child.stderr.on('data', (chunk) => { output += chunk.toString(); });
|
||||||
|
child.on('close', (code) => resolve({ code: code ?? 1, output: output.slice(-4000) }));
|
||||||
|
child.on('error', () => resolve({ code: 1, output: '' }));
|
||||||
|
});
|
||||||
|
}
|
||||||
|
async function checkpoint() {
|
||||||
|
const state = readState();
|
||||||
|
if (state.status === 'blocked' || state.status === 'completed') return false;
|
||||||
|
state.status = 'working';
|
||||||
|
state.currentTask = 'Run local verification, then perform the bounded read-only compatibility probe.';
|
||||||
|
writeState(state);
|
||||||
|
|
||||||
|
for (const [label, command, args] of [
|
||||||
|
['tests', 'npm', ['test', '--', '--runInBand']],
|
||||||
|
['build', 'npm', ['run', 'build']],
|
||||||
|
['lint', 'npm', ['run', 'lint']],
|
||||||
|
]) {
|
||||||
|
const result = await run(command, args);
|
||||||
|
const latest = readState();
|
||||||
|
latest.lastVerification = latest.lastVerification || {};
|
||||||
|
latest.lastVerification[label] = result.code === 0 ? 'passed' : 'failed';
|
||||||
|
latest.lastVerificationAt = new Date().toISOString();
|
||||||
|
latest.nextAction = result.code === 0 ? 'Run the fixed-scope read-only live probe.' : `Fix local ${label} failure before live testing.`;
|
||||||
|
writeState(latest);
|
||||||
|
if (result.code !== 0) {
|
||||||
|
latest.status = 'blocked';
|
||||||
|
latest.blocker = `Local ${label} verification failed.`;
|
||||||
|
writeState(latest);
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const latest = readState();
|
||||||
|
if ((latest.liveTestFailures || 0) >= maxLiveFailures) {
|
||||||
|
latest.status = 'blocked';
|
||||||
|
latest.blocker = 'Maximum consecutive live-test failures reached; live testing stopped.';
|
||||||
|
latest.nextAction = 'Review sanitized protocol diagnostics manually; do not retry live testing.';
|
||||||
|
writeState(latest);
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
const probe = await run('npm', ['run', 'live-test']);
|
||||||
|
const afterProbe = readState();
|
||||||
|
if (probe.code === 0) {
|
||||||
|
afterProbe.status = 'completed';
|
||||||
|
afterProbe.completedMilestones = afterProbe.completedMilestones || [];
|
||||||
|
afterProbe.completedMilestones.push({ task: 'Fixed-scope read-only live compatibility probe passed', completedAt: new Date().toISOString() });
|
||||||
|
afterProbe.blocker = null;
|
||||||
|
afterProbe.nextAction = 'Document live compatibility result and prepare the read-only MVP.';
|
||||||
|
} else {
|
||||||
|
afterProbe.liveTestFailures = (afterProbe.liveTestFailures || 0) + 1;
|
||||||
|
afterProbe.status = afterProbe.liveTestFailures >= maxLiveFailures ? 'blocked' : 'working';
|
||||||
|
afterProbe.blocker = `Read-only live probe failed at the known safe stage; consecutive failures: ${afterProbe.liveTestFailures}.`;
|
||||||
|
afterProbe.nextAction = afterProbe.liveTestFailures >= maxLiveFailures
|
||||||
|
? 'Live testing stopped at the configured failure limit.'
|
||||||
|
: 'Inspect the sanitized failure stage before any further live retry.';
|
||||||
|
}
|
||||||
|
writeState(afterProbe);
|
||||||
|
return afterProbe.status === 'working';
|
||||||
|
}
|
||||||
|
|
||||||
|
async function main() {
|
||||||
|
process.on('SIGTERM', () => { try { fs.closeSync(lock); fs.unlinkSync(lockPath); } catch {} process.exit(0); });
|
||||||
|
try {
|
||||||
|
let keepGoing = await checkpoint();
|
||||||
|
while (keepGoing) {
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, intervalMs));
|
||||||
|
keepGoing = await checkpoint();
|
||||||
|
}
|
||||||
|
} finally {
|
||||||
|
try { fs.closeSync(lock); fs.unlinkSync(lockPath); } catch {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
main().catch((error) => {
|
||||||
|
try {
|
||||||
|
const state = readState();
|
||||||
|
state.status = 'blocked';
|
||||||
|
state.blocker = 'Worker orchestration failed before completing its checkpoint.';
|
||||||
|
state.nextAction = 'Inspect worker error and restart only after confirming no worker is active.';
|
||||||
|
writeState(state);
|
||||||
|
} catch {}
|
||||||
|
process.stderr.write(`${error instanceof Error ? error.message : 'worker failed'}\n`);
|
||||||
|
process.exit(1);
|
||||||
|
});
|
||||||
Reference in New Issue
Block a user