Two-Key Server Linking, Replacing the Shared Token

A document root bug sweep first

Before this, a quieter fix: several features that write to an account’s document root (the cPanel importer, custom Error Pages, Directory Privacy, the File Manager, and WebDAV account setup) carried a stale assumption about where that root was. Deploy from Git and the App Installer had already taught the panel that an account’s serving root can move, but these five had not caught up. They were root-caused and fixed together with regression tests rather than patched one at a time.

Replacing the shared linking token

DNS-only server linking had worked on a single shared token that authenticated traffic in both directions. Revisiting it showed that a single bidirectional secret is weaker than it needs to be, and that linking required a live call from the satellite back to Main, so it could fail on nothing more than a firewall rule.

The replacement is a two-key mutual-authentication scheme, entirely offline:

• Link Key: generated on Main as the first step (Manage Servers, Add Server, pick a role).
• Response Key: generated by the satellite when the Link Key is pasted into its setup screen, and carrying proof that the satellite genuinely held the Link Key.
• Pasting the Response Key into Main’s Complete Link box verifies that proof and finishes the link.

Two independent secrets, one per direction, replace the single shared token, and the handshake never touches the network.

Two bugs the live test caught

Local tests passed before any of this touched real infrastructure. The live test, upgrading a real DNS-only box already linked under the old scheme, caught two things the suite could not, because neither is visible from a fresh database:

1. Adding a server with DNS clustering already enabled failed. A freshly added satellite has no address yet, and the cluster configuration builder produced an invalid entry. Unlinked servers are now left out until linking supplies the address.
2. A box already linked under the old scheme could not get back to the linking screen. The check for “already linked” looked at the wrong fields instead of whether a working secret existed. It now checks the secret.

Both were only reachable by running the upgrade against a real, previously-linked install, which is why we proved this on a real test box before calling it done.

Verified end to end

With both fixes shipped, the full loop was re-run against the real box: Link Key from Main, Response Key back from the satellite, verification on Main, and a real authenticated sync that brought the server online. Three releases went out (v0.16.19 for linking, v0.16.20 and v0.16.21 for the two fixes), each installed on the real test box before the next step.