PR #63072: fix: guard loadState against array-typed pending/paired JSON files

• Repository: openclaw/openclaw
• Author: oc-wonton
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63072

Description (problem / solution / changelog)

Summary

• Problem: pending.json / paired.json can contain [] instead of {}. The nullish coalescing operator (??) passes arrays through because they are truthy.
• Why it matters: UUID-keyed pairing requests assigned to arrays are silently dropped by JSON.stringify on persist, breaking all device and node pairing flows. CLI commands fail with misleading "pairing required" error.
• What changed: Added Array.isArray() guards in loadState for both device-pairing.ts and node-pairing.ts to coerce arrays to empty objects.
• What did NOT change (scope boundary): No changes to persistState, readJsonFile, or any other pairing logic. Only the deserialization guard.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #63035
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: loadState uses pending ?? {} which passes [] through since arrays are truthy. JSON.stringify silently drops non-numeric keys from arrays, so UUID-keyed entries are lost on every persist cycle.
• Missing detection / guardrail: No type guard for array-vs-object on deserialized JSON state files.
• Contributing context (if known): State files can end up as [] from previous version migration or corrupted init.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/infra/pairing-pending.test.ts or a new device-pairing.test.ts
• Scenario the test should lock in: loadState returns {} when state file contains []
• Why this is the smallest reliable guardrail: Tests the exact deserialization boundary where corruption enters
• If no new test is added, why not: The fix is a 2-line guard; happy to add a test if maintainers prefer

User-visible / Behavior Changes

None — this fix restores expected behavior. Device pairing works correctly when state files contain [].

Diagram (if applicable)

Before:
[readJsonFile → []] -> [pending ?? {} → []] -> [assign UUID key → silent] -> [JSON.stringify → []] -> data lost

After:
[readJsonFile → []] -> [Array.isArray check → {}] -> [assign UUID key → works] -> [JSON.stringify → {uuid: ...}] -> data persisted

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Ubuntu 24.04 (Azure Linux)
• Runtime/container: Node.js v22.22.0
• Model/provider: N/A (infrastructure bug)

Steps

1. Ensure devices/pending.json contains []
2. Attempt CLI connection or device pairing
3. Observe "pairing required" rejection

Expected

• Pairing request is stored and approved

Actual

• Pairing request is silently dropped on persist, approval returns null

Evidence

• Trace/log snippets (see issue #63035 for detailed gateway logs)

Human Verification (required)

• Verified scenarios: Code review of both changed files confirms guard matches issue description
• Edge cases checked: null, undefined, [], {}, valid object — all produce correct output
• What you did not verify: Did not reproduce in Docker environment (no Docker setup locally)

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: None — strictly additive guard, no behavior change for valid {} state files.

Changed files

• src/infra/device-pairing.ts (modified, +2/-2)
• src/infra/node-pairing.ts (modified, +2/-2)

PR #63078: fix: guard loadState against array-typed state files

• Repository: openclaw/openclaw
• Author: 4yDX3906
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63078

Description (problem / solution / changelog)

Summary

• Problem: loadState in device-pairing.ts uses pending ?? {} to fall back to an empty object, but when pending.json or paired.json contains [] (an empty array), ?? does not trigger because arrays are truthy. UUID-keyed entries assigned to the resulting array are silently dropped by JSON.stringify, breaking device pairing approval.
• Why it matters: Docker Compose deployments where state files get initialized as [] cannot complete device pairing — approveDevicePairing always returns null.
• What changed: Replaced pending ?? {} with pending && !Array.isArray(pending) ? pending : {} (same for paired) so that array-shaped state files are normalized to {} on load. Added a regression test that seeds both files with [] and verifies the full request → approve → persist round-trip.
• What did NOT change (scope boundary): No changes to readJsonFile, writeJsonAtomic, or any other state file handling. Only the loadState function's fallback logic was tightened.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #63035
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: The nullish coalescing operator (??) only guards against null/undefined, not against unexpected value types like arrays. [] is truthy so pending ?? {} passes the array through.
• Missing detection / guardrail: No type assertion or shape validation on the parsed JSON before assigning to the typed state object.
• Contributing context: State files can end up as [] in Docker Compose deployments when the volume is initialized or reset.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/infra/device-pairing.test.ts
• Scenario the test should lock in: When pending.json and paired.json both contain [], requestDevicePairing → approveDevicePairing should succeed, and persisted files should contain objects (not arrays).
• Why this is the smallest reliable guardrail: A unit test at the loadState consumer level directly exercises the buggy code path with minimal setup.
• Existing test that already covers this: None.

User-visible / Behavior Changes

Device pairing in Docker Compose deployments with array-typed state files will now succeed instead of silently failing.

Diagram (if applicable)

Before:
[readJsonFile returns []] -> [pending ?? {} → []] -> [UUID keys on array] -> [JSON.stringify drops keys] -> [approval fails]

After:
[readJsonFile returns []] -> [Array.isArray check → {}] -> [UUID keys on object] -> [JSON.stringify preserves keys] -> [approval succeeds]

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS (also affects Linux Docker)
• Runtime/container: Node.js / Docker Compose

Steps

1. Ensure devices/pending.json and devices/paired.json contain []
2. Run requestDevicePairing followed by approveDevicePairing
3. Observe result

Expected

• approveDevicePairing returns { status: 'approved', ... }

Actual (before fix)

• approveDevicePairing returns null

Evidence

• Failing test/log before + passing after
• All 32 tests pass including the new regression test

Human Verification (required)

• Verified scenarios: Full request → approve → persist round-trip with []-typed state files
• Edge cases checked: Verified that normal {} state files still work (all 31 existing tests pass)
• What you did not verify: Production Docker Compose deployment end-to-end

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: If a state file somehow contains a non-array, non-object truthy value (e.g., a string), the Array.isArray check alone won't catch it.
  • Mitigation: readJsonFile is typed to return Record<string, T> | null, so non-object returns are already outside the expected contract. The Array.isArray guard handles the most likely failure mode.

_{🔧 Generated by issue-to-pr}

Changed files

• src/infra/device-pairing.test.ts (modified, +39/-1)
• src/infra/device-pairing.ts (modified, +2/-2)

PR #63081: fix(gateway): guard loadState against array-typed pairing state files

• Repository: openclaw/openclaw
• Author: sar618
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63081

Description (problem / solution / changelog)

loadState reads pending.json and paired.json via pending ?? {}, which passes through [] since arrays are truthy. UUID keys set on an array are silently dropped by JSON.stringify, destroying all pairing state on every persist cycle.

Applies the same guard to both device-pairing and node-pairing.

Closes #63035

Summary

• Problem: loadState in device-pairing.ts and node-pairing.ts uses pending ?? {} which does not guard against []. Arrays are truthy, so [] passes through. UUID-keyed entries are set on the array in memory but JSON.stringify silently drops non-numeric array keys, writing [] back to disk on every persist.
• Why it matters: All device pairing operations fail silently. Silent auto-approval returns null, causing CLI Docker connections to be rejected with pairing required (1008) despite valid token auth and correct locality detection. Affects any deployment where state files contain [] instead of {}.
• What changed: Added Array.isArray() guards in loadState for both device-pairing.ts and node-pairing.ts so that [] is coerced to {} on read.
• What did NOT change (scope boundary): No changes to persistState, approveDevicePairing, requestDevicePairing, pairing locality logic, or auth validation. Write path is unmodified — the fix is read-side only.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #63035
• Related #55113
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: loadState assigns pending ?? {} without checking the type. readJsonFile can return [] (a valid JSON parse result), which is truthy and passes through the nullish coalescing operator. UUID keys are then set on an array object. JSON.stringify serializes arrays by numeric index only, silently dropping all string-keyed entries on persist.
• Missing detection / guardrail: No type assertion or Array.isArray check on the parsed JSON before assigning to pendingById / pairedByDeviceId / pairedByNodeId. No test coverage for malformed state file recovery.
• Contributing context (if known): Unknown what originally wrote [] to the state files — possibly an older version migration, a failed init path, or a race condition.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/infra/device-pairing.test.ts
• Scenario the test should lock in: loadState recovers gracefully when pending.json or paired.json contain [] instead of {}. A pairing request created after recovery should be findable by approveDevicePairing.
• Why this is the smallest reliable guardrail: Directly exercises the read path with the known bad input.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: Test should be added. I did not have a working test harness to validate against — happy to add one if a maintainer can point to the existing test setup pattern for device-pairing.ts.

User-visible / Behavior Changes

• Device pairing silent auto-approval works correctly when state files contain [] instead of {}
• CLI Docker commands no longer fail with pairing required when state files are corrupted

Diagram (if applicable)

Before:
readJsonFile(pending.json) -> [] -> pendingById = [] -> UUID key set on array -> JSON.stringify -> [] -> data lost

After:
readJsonFile(pending.json) -> [] -> Array.isArray check -> pendingById = {} -> UUID key set on object -> JSON.stringify -> {"uuid": ...} -> data preserved

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Ubuntu (headless)
• Runtime/container: Docker Engine + Compose v2, host networking, network_mode: "service:openclaw-gateway" for CLI
• Model/provider: Not model-specific
• Integration/channel (if any): N/A
• Relevant config (redacted): gateway.auth.mode: "token", gateway.bind: "lan", standard docker-compose.yml from repo

Steps

1. Deploy with Docker Compose (gateway + CLI containers sharing network namespace)
2. Ensure devices/pending.json and devices/paired.json contain [] instead of {}
3. Run: docker exec openclaw-openclaw-cli-1 /usr/local/bin/openclaw cron list

Expected

• CLI command succeeds, cron jobs listed

Actual

• gateway closed (1008): pairing required
• approveDevicePairing returns null because loadState reads [] and finds no pending entry

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Debug instrumentation confirmed:

[PERSIST] {"pendingKeys":["4bf6458c-631f-44b2-ba9e-d27f3aa96e09"],"pairedKeys":[],"baseDir":"default"}
[APPROVE-STATE] {"requestId":"4bf6458c-631f-44b2-ba9e-d27f3aa96e09","pendingKeys":[],"pairedKeys":[]}

persistState writes with the UUID key present, but loadState immediately reads back empty — because JSON.stringify on an array drops string keys.

After replacing state files with {} and restarting, CLI commands work immediately.

Human Verification (required)

• Verified scenarios: Replaced [] with {} in both state files, restarted gateway, CLI cron list returned 14 jobs successfully.
• Edge cases checked: Both device-pairing.ts and node-pairing.ts patched with the same guard.
• What you did not verify: Did not run the full test suite (no local test harness). Did not verify node-pairing.ts end-to-end (no node pairing test environment). Did not identify what originally wrote [] to the state files.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: If a future code path intentionally writes [] to state files expecting array semantics, this guard would silently convert it to {}.
  • Mitigation: The type annotations (Record<string, ...>) on pendingById and pairedByDeviceId explicitly expect objects, not arrays. Array state files are always invalid.

Changed files

• src/infra/device-pairing.ts (modified, +2/-2)
• src/infra/node-pairing.ts (modified, +2/-2)

PR #63086: fix(device-pairing): coerce array-typed state files to plain objects in loadState

• Repository: openclaw/openclaw
• Author: openperf
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63086

Description (problem / solution / changelog)

Summary

• Problem: loadState() in src/infra/device-pairing.ts:111 and src/infra/node-pairing.ts:141 uses nullish coalescing (pending ?? {}, paired ?? {}) to default the return value of readJsonFile(). When pending.json or paired.json contains a JSON array ([]) instead of an object, the array passes through because arrays are truthy in JavaScript. UUID-keyed pairing requests assigned onto the array are then silently dropped by JSON.stringify() on the next persistState() call (line 119), permanently destroying all device/node pairing state. Every Docker CLI command fails with gateway closed (1008): pairing required.

• Root Cause: readJsonFile<T>() in src/infra/json-files.ts:26 is a generic JSON deserializer that returns whatever JSON.parse() produces — including arrays and primitives. The TypeScript generic T provides zero runtime safety (it uses as T cast). The ?? {} guard in loadState() only catches null and undefined, not type mismatches. When the persisted file contains [], the array is truthy, so ?? does not trigger. JavaScript silently accepts UUID string-key assignments on arrays (arr["some-uuid"] = value works in memory), but JSON.stringify() only serializes numeric-index entries for arrays, discarding all string-keyed data. This creates a permanent self-amplifying data-loss loop: persistState() writes [] back to disk, and every subsequent loadState() reads [] again. The sibling module src/infra/device-bootstrap.ts (line 136) already guards against this exact scenario with an explicit Array.isArray() check, but the pairing loaders were missing this validation.

• Fix: Introduce a shared, exported coerceToRecord<T>(value: unknown): Record<string, T> helper in src/infra/pairing-files.ts that rejects null, undefined, arrays, and primitive values, returning {} for any non-plain-object input. Replace ?? {} with coerceToRecord() in both device-pairing.ts and node-pairing.ts loadState() functions. This approach avoids side effects because: (1) it follows the existing project pattern in device-bootstrap.ts; (2) it does not modify the generic readJsonFile() or writeJsonAtomic() utilities used by 20+ callers; (3) for valid Record<string, T> inputs it returns the original object reference with zero overhead; (4) the fix is self-healing — the first loadState() coerces [] to {}, and the next persistState() writes a valid object back to disk, permanently repairing the corrupted file.

• What changed:

  • src/infra/pairing-files.ts — added exported coerceToRecord<T>() helper with JSDoc (+16 lines)
  • src/infra/device-pairing.ts — imported coerceToRecord, replaced pending ?? {} and paired ?? {} with coerceToRecord(pending) and coerceToRecord(paired) in loadState() (+3/-2 lines)
  • src/infra/node-pairing.ts — identical change to its loadState() (+3/-2 lines)
  • src/infra/pairing-files.test.ts — added 7 unit tests for coerceToRecord covering null, undefined, empty array, non-empty array, primitives, plain object pass-through, empty object pass-through (+43 lines)
  • src/infra/device-pairing.test.ts — added 1 integration test that seeds [] into both state files and verifies full request-approve-persist round-trip with JSON round-trip validation (+38 lines)

• What did NOT change (scope boundary): readJsonFile() and writeJsonAtomic() in json-files.ts are untouched — they are generic utilities and type validation is the caller's responsibility. persistState() is unchanged. No changes to gateway handshake logic, CLI, auth flow, or any module outside src/infra/. No changes to device-bootstrap.ts (it already has its own guard). Total: 5 files changed, +103/-4 lines.

Reproduction

1. Deploy OpenClaw v2026.4.8 via Docker Compose with gateway and CLI containers sharing a network namespace
2. Ensure ~/.openclaw/devices/pending.json and paired.json contain [] instead of {} (can occur from version migration or corrupted init)
3. Run: docker exec openclaw-openclaw-cli-1 /usr/local/bin/openclaw cron list
4. Observe error: gateway closed (1008): pairing required
5. Gateway log shows: closed before connect remote=127.0.0.1 code=1008 reason=pairing required
6. Replace both files with {} and restart gateway — CLI works immediately (confirming root cause)

Risk / Mitigation

• Risk: If any legitimate use case stores arrays in pending.json or paired.json, the data would be silently converted to an empty object.

• Mitigation: The pairing state schema (DevicePairingStateFile, NodePairingStateFile) explicitly defines pendingById and pairedByDeviceId/pairedByNodeId as Record<string, T>. Arrays are never a valid state format. The sibling device-bootstrap.ts already applies the same coercion pattern in production without issues.

• Risk: node-pairing.ts change is not covered by a dedicated integration test.

• Mitigation: The shared coerceToRecord() function is thoroughly unit-tested with 7 cases. The node-pairing.ts loadState() is structurally identical to device-pairing.ts and calls the same shared helper. The device-pairing integration test validates the full pipeline end-to-end.

• Risk: Test coverage — 43 tests all pass (32 device-pairing + 11 pairing-files), zero regressions confirmed via npx vitest run --config vitest.infra.config.ts.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway / orchestration
• Auth / tokens
• Memory / storage

Linked Issue/PR

Fixes #63035

Changed files

• src/infra/device-pairing.test.ts (modified, +38/-0)
• src/infra/device-pairing.ts (modified, +3/-2)
• src/infra/node-pairing.ts (modified, +3/-2)
• src/infra/pairing-files.test.ts (modified, +43/-0)
• src/infra/pairing-files.ts (modified, +16/-0)