Failover: the trust ratchet does not survive a restart — a superseded local route leads again

[KesleyDavid]

The trust ratchet holds inside one CandidateRotation value, but not across a restart. A hand-typed local route that has already been upgraded away from leads the rotation again on the next launch, and the long-lived bearer goes with it.

The sequence

Every step is reachable through normal use.

1. Someone types a LAN address in Settings. Session.updateAddress (ios/App/Session.swift:535-541) builds it with priority: 0 and puts it at the head:

updated.promote(endpoint)
updated.endpoints = [endpoint] + existingRoutes.filter { $0.url != endpoint.url }

2. That route fails. CandidateRotation.advance upgrades to a hosted or tailnet route and drops the local one from the rotation — the ratchet working as intended.

3. The protected route says hello, and rememberWorkingRoute() (Session.swift:478-484) calls promote(winner). But promote (Failover.swift:307-319) only assigns activeEndpoint and appends the winner if it was missing:

public mutating func promote(_ winner: CompanionEndpoint) {
    activeEndpoint = winner
    host = winner.host
    port = winner.port
    if let existing = endpoints,
       !existing.contains(where: { $0.url == winner.url }) {
        endpoints = existing + [winner]
    }
    ...
}

It never reorders and never reprioritises, so the priority: 0 local route is still first in endpoints.

4. orderedEndpoints (Failover.swift:196-214) sorts by priority and original offset only, and appends activeEndpoint only when it is missing — it is never pulled to the front:

candidates = candidates.enumerated().sorted {
    $0.element.priority == $1.element.priority
        ? $0.offset < $1.offset
        : $0.element.priority < $1.element.priority
}.map(\.element)

5. If the best-effort endpoint refresh 404s, fails, or is cancelled — all deliberately tolerated — that order is what persists.

6. Next launch, CandidateRotation(endpoints: saved.orderedEndpoints) (Session.swift:155) starts from the cleartext route again, treats it as the explicit local choice, and hands it the stored bearer.

Why it matters

The ratchet exists so that a connection which has reached a protected route does not walk back onto cleartext carrying a long-lived token. That guarantee currently lives in the lifetime of a CandidateRotation value. A process restart — or anything that rebuilds the rotation from the store — resets it.

Nothing is corrupted, and it needs a hand-typed local address to have been used at least once. But after that, the reset is automatic and silent.

Shape of a fix

The version that worked when I hit the same thing while porting: make the ordering itself carry the upgrade, so a route already in use that protects credentials leads the stored order regardless of a lower priority number. Reaching a protected route is one-way; the superseded route can stay in endpoints for display and for a future manual choice without being what the rotation reads as the preferred candidate.

That keeps the escape hatch intact — typing the local address again makes it active and the priority order applies once more, which matters when the hosted route is down and someone needs the LAN.

How it was found

Porting the companion to Android. A reviewer traced the same sequence in the Kotlin port, reproduced it with a temporary test, and then checked whether the Swift it was ported from had the same shape. It does. Verified against main at 3557e748; read from source rather than run on a device, since I have no Apple hardware here.

The Android port is deliberately diverging on this point rather than mirroring it, since it is a credential path.

[lightcloud00]

Protected-route ordering follow-up ready

Clean local head 18e9eefdcce0b7d20ca19b338e36d85079b6764b fixes the remaining ordering regression so a credential-protecting active endpoint stays ahead of lower-priority routes after restart while preserving explicit alternatives.

Eight focused regression tests and all 183 Swift tests pass. This will be published as a contributor follow-up to PR #500 after the active PR #326 gate.

[lightcloud00]

Contributor follow-up published

The protected-route ordering repair is now available as santhiprakash/OpenMausBot#2, targeting the exact contributor branch behind upstream PR #500.

• exact head: 18e9eefdcce0b7d20ca19b338e36d85079b6764b
• remote SHA readback matches
• full Node 24 fleet gate passed
• CodeRabbit is green and the contributor PR is mergeable
• 8 focused ordering regressions and all 183 Swift tests passed before publication

This keeps every credential-protecting route ahead of cleartext after restart while retaining intentional alternatives. The merge attempt was made once and GitHub correctly denied it because lightcloud00 has read-only access to the contributor fork. The remaining action is for santhiprakash to merge the one-commit follow-up so upstream PR #500 receives the fix without rewriting contributor history.

[KesleyDavid]

#500 fixes this, and I have stood down rather than opening anything of my own.

I had a change written for it before I saw that PR. Reading the diff, the conditional pin — activeEndpoint leads only when the sorted head is cleartext, guarded by !sortedHead.protectsCredentials — is the right shape, and narrower than what I had. It also matters more than it looks: once the head is protected, CompanionEndpoint.automaticCandidates drops every cleartext route from the rotation, so the bearer is not merely deprioritised on that path, it is excluded.

Legacy connections are covered too: if let activeEndpoint means a connection saved without one keeps its priority order, so someone who is on a hand-typed LAN address by choice is not quietly moved.

Nothing to add from my side. The Android port carries the equivalent rule, with the ratchet state living in the persisted activeEndpoint rather than in a new field — same idea, arrived at independently.