Skip to content

PairSecurity : Check a new epoch's key against the store links - #54

Open
Mark7888 wants to merge 9 commits into
masterfrom
claude/magical-hamilton-q9sjfe
Open

Mark7888 wants to merge 9 commits into
masterfrom
claude/magical-hamilton-q9sjfe

Conversation

@Mark7888

@Mark7888 Mark7888 commented Nov 5, 2026 •

Copy link
Copy Markdown
Owner

Phase 1 contract change from the relay trust plan. Text only: no byte layout, derivation, vector or proto changes. The implementation is #55, stacked on this branch.

Why

A modified relay can currently get a group's key without any user action:

  • Pairing: an inviter wraps the group key to whatever public key a join notice carries. It doesn't check that the token is one it minted and doesn't ask the user.
  • Rekey: a device installs any wrapped key for a higher epoch. A device's public key is no secret, so the relay can wrap a key of its own to every device, and they all switch to it.

What changes

  • spec/crypto.md 1.4
    • §7.1 (new): before installing a key for epoch E, a client walks the store links from E back to its current epoch and checks they end at its own store key.
      • The relay serves the links whether or not the group's store is on.
      • Missing links or a refusal fail the check: a relay can claim to be too old to have them.
      • A refused key is checked again when the relay offers it again, and never installed without passing.
    • §11.4: two new rows for what this leaves open (a joining device's first key, and a revoked device working with the relay). The roster row now names the fingerprint the user checks.
    • The §7 table and the §8 mapping point to §7.1. There's a revision note; every vector is byte-identical.
  • docs/internal/SPECS.md
    • §3.2: the inviter acts only on a token it minted, still open and unused, and wraps only after the user confirms the joining device's name and fingerprint. The joiner shows its own fingerprint while it waits.
    • §3.3: the revoke dialog shows fingerprints, devices check the new key, and every rekey must carry a store link (today it's required only while the group holds store items).
    • §4.6: store links are served while the store is off.
  • docs/internal/plans/relay-trust-hardening.md: the plan for both phases, including version compatibility.

Compatibility

Text only, so nothing changes until #55 lands. Once it does:

The plan's §3.5 has the full matrix.

🤖 Generated with Claude Code

https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9

@Mark7888 Mark7888 changed the title Check a new epoch's key against the store links PairSecurity : Check a new epoch's key against the store links Nov 6, 2026
A modified relay can currently get a group's key without any user
action: an inviter wraps to whatever key a join notice carries, and a
device installs any new-epoch key the relay pushes. A joiner also cannot
tell who wrapped its key, and the revoke dialog shows names only.

The plan fixes this in two phases: client-side checks that ship without
a wire change, then authenticated wraps, pairing secrets and device
certificates as a crypto and protocol change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
Adds what happens for each mix of old and new clients and relays, in
both phases, and settles two cases the plan left open: a relay older
than v1.2.0 has no store links to check a new epoch against, and a
rekey by a client older than v1.2.0 carries none. Both are refused, as
a hostile relay could fake either.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
Every merge to master ships to the Beta channel, so each client now
lands together with its app, docs go in the PR that changes the
behaviour, and Verify devices comes last, once both apps can open
everything it produces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
Only the shared contracts need their own PR. The server, both clients
and both apps land together, which also keeps master from ever holding
one app that cannot read what the other produces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
A wrapped key only proves it was made for the device that opens it, and
a device's public key is no secret: a relay can wrap a key of its own to
every device at the next epoch and they install it. A store link is the
proof the relay cannot make, since sealing one takes the previous key.

- spec/crypto.md 1.4: §7.1 makes the check a MUST, refuses a key whose
  links are missing, and lists in §11.4 what it leaves open (a joining
  device's first key, a revoked device working with the relay). No byte
  layout changes; every vector is byte-identical.
- SPECS §3.2: an inviter confirms the joining device's name and
  fingerprint before it wraps, and acts only on tokens it minted.
- SPECS §3.3: the revoke dialog shows fingerprints, devices check the
  new key, and every rekey must carry a link, not only while the group
  holds store items.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
A v1.2 relay refuses StoreLinksRequest while a group's store is off,
the default, which would make every rekey of such a group fail the new
check. The spec now has the relay serve them either way, treats a
refusal as no links, and checks a refused key again when the relay
offers it again rather than never.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
A relay controls the version and features it reports, so a plan that
fell back to Phase 1 pairing when the relay or the other device looked
old let a hostile relay unlock the weaker path by claiming to be old.

The plan now says so up front: no client takes a weaker path because of
anything the relay says. Phase 2 clients drop version-0x01 wraps and
unproven joins entirely, with no per-group flag to downgrade. An old
relay, or an old app on the other side, makes pairing and rekeys fail
with a message to update instead. The first Phase 2 rekey of an existing
group doubles as the step that certifies its devices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
@Mark7888
Mark7888 force-pushed the claude/magical-hamilton-q9sjfe branch from 485eb3c to 120f171 Compare November 13, 2026 22:24
Phase 2 is the pairing change the protocol compatibility plan was
written for. The rollout now uses its machinery instead of a separate
client version field:

- Phase 2 apps speak level 2 and need CAPABILITY_PAIRING_V2 to pair or
  rekey; without it they refuse on the device and say the relay needs
  updating. There is still no fallback.
- The relay refuses pairing and rekey requests from level-1 sockets
  with CLIENT_OUTDATED. Rekeys join the pairing requests because a
  level-1 rekey would strand the Phase 2 devices.
- The roster carries each device's last protocol level, which the relay
  already stores, so an app can warn before a rekey cuts off old ones.
- ProtocolMin stays 1 so old devices keep syncing, and rises to 2 in a
  later Stable release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01883ho3VieWfSCRWEa5iBK9
Phase 2 changes how every key change is wrapped, so there is no mix of
old and new devices in which key changes keep working. Instead of
refusing old apps request by request while they fall behind silently,
the relay that ships Phase 2 accepts level 2 only: old apps are refused
at the connection with the 426 that tells them to update, and the relay
and every app are updated together.

- relay-trust-hardening: ProtocolMin and ProtocolMax both 2, the
  rollout table rewritten, the later minimum-raising release and the
  per-device level in the roster dropped.
- protocol-compatibility: §4 describes the pairing change as a full
  break, §6's open question is decided (no fallback), and §2-§3 no
  longer say the pairing change avoids a connection refusal.

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