Skip to content

Add tooling to recover daemon-host local pairing access #875

@Aaronontheweb

Description

@Aaronontheweb

Problem

The bootstrap hardening work in #872 makes local daemon-host access fail loudly when secrets.json contains a stale or missing DeviceToken that no longer matches any device in devices.json. That is the right security behavior, but today the operator recovery path is manual and error-prone.

Current diagnostics can detect:

  • bootstrap incomplete state before first successful non-local startup
  • completed bootstrap with stale or missing daemon-host local token

But there is no first-class repair tool for either case.

Goal

Add a supported repair workflow that restores daemon-host local control-plane access without forcing operators to manually edit devices.json / secrets.json, and without silently resetting all remote pairings.

Proposed scope

Implement one of:

  • doctor --fix support for pairing/bootstrap repair, or
  • a dedicated command like netclaw pair recover-local-access

The tool should:

  1. detect the broken local pairing states already surfaced by ExposureModeDoctorCheck
  2. repair local daemon-host access by writing devices.json and secrets.json atomically
  3. preserve existing remote paired devices when possible
  4. avoid silently regenerating bootstrap state on top of completed installs
  5. fail loudly when safe in-place repair is not possible

Required behavior

Case 1: bootstrap incomplete

When bootstrap has not completed and local bootstrap state is inconsistent, the tool should offer a safe reset of bootstrap artifacts so the next non-local daemon start can reseed cleanly.

Case 2: bootstrap completed, daemon-host local token stale/missing

When existing remote devices still exist but the daemon-host local token is stale or missing, the tool should create or rotate a daemon-host local paired device without wiping unrelated remote devices.

Constraints

  • Do not silently delete all pairings unless the operator explicitly confirms a full reset
  • Do not silently generate a fresh bootstrap token/device pair on top of completed installs
  • Do not require raw-token recovery from devices.json alone, since that is impossible by design
  • Prefer offline-safe repair steps when the daemon is stopped or when direct local filesystem access is available

Acceptance criteria

  • operators can recover daemon-host local netclaw daemon pair / local CLI access from a detected mismatch state
  • remote devices are preserved when a local-only repair is possible
  • netclaw doctor remediation points to the repair command/path
  • tests cover incomplete bootstrap reset and completed-install local-token repair paths

Context

This gap came out of the review/follow-up work on #872 and the related re-entrant init discussion in #455.

Metadata

Metadata

Assignees

No one assigned

    Labels

    remote-accessNetwork exposure, device pairing, tunnels, webhooks, and remote ingresstuiTerminal UI (Termina) issues

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions