Federation handshake prototype between two instances (did:web + trust list)

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/koinos#18

claude-desktop commented

2026-04-14 20:42:53 +00:00

Collaborator

User story

As an instance administrator, I want to establish a bilateral federation trust with another Koinos instance through a guided handshake, so that my practitioners can invite theirs to teleexpertise cases.

Acceptance criteria

Instance identity

Each instance publishes /.well-known/did.json with its Ed25519 signing key.
/.well-known/koinos/federation.json describing capabilities (Matrix server name, FHIR base URL, protocol version).

Handshake flow

Admin A enters peer B's host URL → backend fetches B's DID + federation doc → displays fingerprint for verification.
Out-of-band fingerprint confirmation (the two admins compare a short hex over phone/email).
Admin A approves → peer added to trust list (DB row + pinned key).
Symmetrical: admin B does the same on their side.
Trust list visible in admin UI; peers can be removed.

Enforcement

Matrix federation remains at the homeserver layer; Koinos adds a whitelist check on inbound room invites for koinos.case rooms.
FHIR cross-instance token validation accepts tokens signed by the peer's pinned key only.

Tests

Integration test across two Compose stacks: trust establishment + cross-instance Matrix room creation.

Out of scope

ActivityPub federation (v0.4).
Trust list import/export (later admin chore).

References

spec/03-architecture/02-federation.md.
spec/08-roadmap-mvp.md — step #18.

## User story **As an instance administrator**, I want to establish a bilateral federation trust with another Koinos instance through a guided handshake, **so that** my practitioners can invite theirs to teleexpertise cases. ## Acceptance criteria ### Instance identity - [ ] Each instance publishes `/.well-known/did.json` with its Ed25519 signing key. - [ ] `/.well-known/koinos/federation.json` describing capabilities (Matrix server name, FHIR base URL, protocol version). ### Handshake flow - [ ] Admin A enters peer B's host URL → backend fetches B's DID + federation doc → displays fingerprint for verification. - [ ] Out-of-band fingerprint confirmation (the two admins compare a short hex over phone/email). - [ ] Admin A approves → peer added to trust list (DB row + pinned key). - [ ] Symmetrical: admin B does the same on their side. - [ ] Trust list visible in admin UI; peers can be removed. ### Enforcement - [ ] Matrix federation remains at the homeserver layer; Koinos adds a whitelist check on inbound room invites for `koinos.case` rooms. - [ ] FHIR cross-instance token validation accepts tokens signed by the peer's pinned key only. ### Tests - [ ] Integration test across two Compose stacks: trust establishment + cross-instance Matrix room creation. ## Out of scope - ActivityPub federation (v0.4). - Trust list import/export (later admin chore). ## References - `spec/03-architecture/02-federation.md`. - `spec/08-roadmap-mvp.md` — step #18.

claude-desktop added this to the v0.1 milestone

claude-desktop added the

area:federation

type:user-story

labels

claude-desktop referenced this issue

2026-04-14 20:43:05 +00:00

As a practitioner, I can invite a colleague from a peer instance to my case #19