Skip to content

PairSecurity : Confirm joins and check new keys against a hostile relay - #55

Open
Mark7888 wants to merge 8 commits into
claude/magical-hamilton-q9sjfefrom
claude/magical-hamilton-q9sjfe-impl
Open

Mark7888 wants to merge 8 commits into
claude/magical-hamilton-q9sjfefrom
claude/magical-hamilton-q9sjfe-impl

Conversation

@Mark7888

@Mark7888 Mark7888 commented Nov 5, 2026 •

Copy link
Copy Markdown
Owner

Phase 1 of docs/internal/plans/relay-trust-hardening.md: the implementation. It's stacked on #54, the spec change, and targets that branch. Retarget it to master once #54 merges. No proto changes.

What it fixes

A modified relay could get a group's key without the user doing anything:

  1. Pairing: an inviter wrapped the group key to whatever public key a join notice carried.
  2. Rekey: a device installed any wrapped key for a newer epoch the relay pushed.

Changes, one commit per area

  • Server
    • Every rekey must carry a store link. A rekey without one gets CLIENT_OUTDATED; only clients older than v1.2.0 send none.
    • Store links are served whether or not the group's store is on. Released v1.2 relays refuse them while the store is off, which is the default.
  • Go client
    • A join notice no longer wraps anything. It becomes a JoinRequest (via Handlers.OnJoinRequest and Invitation.Request), and only Confirm wraps the key.
    • A notice is acted on only for a token this client minted, still open and not yet claimed.
    • A key for a new epoch is installed only after chainsBack succeeds: the store links must lead from it to the key the device holds (spec/crypto.md §7.1). Missing links, a refusal, or a chain ending anywhere else gives ErrUnverifiedKey and OnKeyRefused.
    • The check runs off the read loop, one key at a time.
  • Desktop
    • Join requests are held as plans in the status. ConfirmJoin and RejectJoin are the only way in, with new endpoints under /api/pairing/join-requests/.
    • A dialog at the top of the app asks, with the joining device's fingerprint, whichever tab is open.
    • Fingerprints appear in Devices, the revoke dialog and Settings.
    • A refused key shows as a notice.
    • The joining side now waits up to 5 minutes instead of 30 seconds, since the other device's user confirms first.
  • TypeScript client and Android
    • The same two fixes in the client (epochs.ts, JoinRequest, onKeyRefused).
    • A sheet above every tab asks to add or turn down a joining device.
    • The setup screen shows this phone's fingerprint.
    • Devices, the remove sheet and Settings show fingerprints, and the Sync screen shows a refused key.
  • Docs site: add a device, devices, settings, troubleshooting and security pages, plus retaken desktop screenshots and a new one of the join dialog.

Changes from the rebase onto master

  • Several groups per installation: switching, adding or leaving a group clears pending join requests and a refused-key notice, on desktop (resetGroupState) and Android (resetScreens).
    • A join request confirmed after its invitation ended is refused, in both clients. Otherwise a request shown before a switch could have been answered with the other group's key.
  • Demo mode:
    • The demo relay (src/core/demo/relay.ts, which replaced the test fake relay) serves store links with or without a store and carries the hostile-relay test hooks.
    • Simulated devices confirm their joins. A simulated device joining with the phone's own code now gets the real confirmation sheet.
  • Bug found by master's tests: an inviter judged an invitation's expiry by the relay's clock, so a device whose clock ran ahead of the relay's would ignore every join. Invitations now stay open for five minutes on the device's own clock. The TypeScript fix is in its commit; the Go fix is the last commit, with a test for a skewed relay clock.
  • The Settings screenshot is retaken on master's new layout.

Tests

  • Hostile-relay tests in both clients. A fake relay pushes forged keys four ways (its own links, no link, relay older than the store, store switched off) and fake join notices (unknown token, second notice for the same token, expired invitation, turned-down request). The honest rekey is the control, including one across two epochs at once.
  • Table tests for chainsBack in Go and TypeScript.
  • Server: a rekey without a link is refused; links are served with the store on and off.
  • Desktop: the service holds and answers join plans, and the HTTP gate refuses a confirm without a plan id.
  • Interop: npm run interop pairs the TypeScript and Go clients through the new confirmation, checks the fingerprint the Go peer agreed to, and verifies each other's rekeys against a real relay and Redis.

Checks run locally after the rebase, all passing:

  • Go: go test -race ./... in server, pkg/tppclient and desktop; golangci-lint v2.6.2; make fmt-check.
  • Desktop UI: npm run build.
  • Mobile: npm test (479 tests), lint, typecheck and interop.
  • Docs site: npm run build.

The Android app was not run on a device; its screens are checked only by type checks and lint.

Compatibility

  • Pairing: works in both directions with older apps. An older inviter still hands the key over without asking, and an older joiner doesn't show its own fingerprint on the join screen.
    • An older desktop joiner still gives up after 30 seconds, so the user has to confirm within that time. An older Android joiner waits 2 minutes.
  • Rekeys: new apps refuse new keys on a relay without this PR whenever the group's store is off, which is the default. Update the relay together with the apps.
  • Old clients: apps older than v1.2.0 can no longer revoke devices.

The plan's §3.5 has the full table.

🤖 Generated with Claude Code

https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9

@Mark7888 Mark7888 changed the title Confirm joins and check new keys against a hostile relay PairSecurity : Confirm joins and check new keys against a hostile relay Nov 6, 2026
@Mark7888
Mark7888 force-pushed the claude/magical-hamilton-q9sjfe-impl branch from 391f363 to 864cf3c Compare November 13, 2026 13:53
@Mark7888
Mark7888 force-pushed the claude/magical-hamilton-q9sjfe branch from 485eb3c to 120f171 Compare November 13, 2026 22:24
@Mark7888
Mark7888 force-pushed the claude/magical-hamilton-q9sjfe-impl branch 2 times, most recently from 0365e9e to db2d941 Compare November 13, 2026 23:15
The remaining devices now check a new epoch's key against its store
link (spec/crypto.md §7.1), so a rekey without one would strand them,
store items or not. The store refuses it with ErrStoreLinkRequired and
the relay answers CLIENT_OUTDATED, as it already did for a group with
items: only a client older than the store sends none.

The check moves to the end of the rekey script's validation, so a
rekey that is wrong in another way is still told so first. The script
no longer reads the store index, which existed only for the old rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
Devices now check every new epoch's key against the store links
(spec/crypto.md §7.1), and a group's store is off until the admin turns
it on, so refusing the links with STORE_DISABLED would have made every
rekey of such a group fail the check. The links are opaque to the relay
and the store switch has nothing to do with them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
Two ways a relay could get a group key without the user doing anything
are closed here.

- Pairing: a join notice no longer wraps the group key. It becomes a
  JoinRequest, delivered to Handlers.OnJoinRequest and
  Invitation.Request, and only JoinRequest.Confirm wraps; Reject ends
  the invitation with ErrJoinRejected. A notice counts only for a token
  this client minted, still open and not yet claimed (SPEC §3.2).
- Rekey: a delivered key for a newer epoch is installed only when the
  store links chain it back to the key this device holds
  (spec/crypto.md §7.1). Missing links, a relay that refuses them, or a
  chain ending anywhere else refuse the key with ErrUnverifiedKey and
  Handlers.OnKeyRefused. The check makes a request, so it runs off the
  read loop, one key at a time.
- Device.Fingerprint and Client.Fingerprint, for the dialogs that show
  them.

A hostile-relay harness in the internal tests pushes forged keys and
made-up join notices. The interop Go peer confirms the join it awaits
and reports the fingerprint it agreed to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
The Go client now holds a join until the user confirms it; this is the
desktop's half.

- Service: join requests are held as plans with an id, listed in the
  status, and answered with ConfirmJoin or RejectJoin, the only way a
  device is admitted through an invitation. A key the client refused is
  kept as a note until a key is installed. This device's fingerprint is
  in the status and every roster device carries its own.
- Joining waits up to the token's five minutes rather than one request's
  thirty seconds: the other device's user confirms first.
- UI: a dialog at the top of the app asks to add or turn down a device,
  with its fingerprint, whichever tab is open. The join panel shows this
  device's fingerprint and says what it is waiting for. Devices, the
  revoke dialog and Settings show fingerprints, and a refused key shows
  as a notice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
The same two fixes as the Go client, for the Android app's core.

- Pairing: a join notice becomes a JoinRequest, delivered to
  onJoinRequest and Invitation.request; only its confirm wraps the key,
  and reject rejects Invitation.joined with 'join-rejected'. A notice
  counts only for a token this client minted, still open and not yet
  claimed. A joiner now waits up to the token's five minutes.
- Rekey: a delivered key for a newer epoch is installed only when the
  store links chain it back to the key this device holds (chainsBack,
  spec/crypto.md §7.1); otherwise onKeyRefused gets an 'unverified-key'
  error. Keys are checked one at a time.

The fake relay serves store links and can push forged keys and made-up
join notices; the interop tests confirm the join on both sides and
check the fingerprint the Go peer agreed to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
- A sheet above every tab asks to add or turn down a device that used
  this phone's invitation, with its fingerprint. It cannot be dismissed
  without an answer, and goes away when the code expires.
- The setup screen shows this phone's fingerprint for the other device
  to compare, and says it is waiting while that device confirms.
- Devices and the remove sheet show each device's fingerprint, Settings
  shows this device's, and the Sync screen says when the relay offered
  a key this phone could not verify.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
- Add a device: the member is asked to check the new device's
  fingerprint before it gets the key, with a screenshot of the dialog.
- Devices: every device shows its fingerprint, the revoke dialog lists
  them, and each remaining device checks the new key.
- Settings: this device's fingerprint.
- Troubleshooting: what a refused key means and how to recover.
- Security: adding a device, the key check, and what a hostile relay
  can still do.
- Retake the desktop Devices, revoke, pairing code and Settings
  screenshots, from the built UI against a mocked local API.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
An inviter dropped a join whose invitation had expired by the relay's
reported time, read on its own clock: a device whose clock runs ahead
of the relay's would ignore every join. Master's new demo relay, with
its injected clock, showed it in the TypeScript client, which was fixed
in its own commit; this is the same fix here.

- An invitation stays open for five minutes on this device's clock, the
  relay's token lifetime. JoinRequest.ExpiresAt is that time too, so the
  desktop drops a stale request by its own clock.
- Confirm refuses once its invitation has ended, as when this device
  switched or left its group after the request was shown: the key on
  hand may not be the group it was for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants