@matrix/federation

Matrix federation layer for cross-realm messaging with:

• Tolerant MXURI parsing (legacy compact + segmented /-/ form)
• Dual mailbox namespaces (Strangler Fig)
  • legacy: public.ingress.<realm> (Matrix-3 compatibility)
  • mx ingress: mx/in/1/<realm>/<shard> (MXINGRESS/1)
• Dual envelope profiles (Strategy)
  • legacy: Matrix-3 request/reply envelopes
  • mxenv1: MXENV/1 envelopes (Cmd|Evt|Result|Sub|Unsub|Nack)
• Edge gateway bridging mailbox messages ↔ internal bus (mx/1/<realm>/<toPath>)
• Federation subscription leasing (streaming Evt forwarding)
• Session directory (principal → active tab realms) for unsolicited push
• Hierarchical routing overlay (MXROUTE-style route inbox forwarding)
• Pluggable transport with in-memory brokers for deterministic tests

No external npm dependencies are required to run unit + integration tests.

Run

npm test

Read the full design

Start with DESIGN.md.

Code map

• Encoding + routing primitives

  • src/uri.ts — tolerant MXURI parsing + canonicalization
  • src/topics.ts — mailbox topics + internal topics + route inbox topics
  • src/envelope.ts + src/envelope_codec.ts — legacy + MXENV/1 envelopes, tolerant decoding, profile-specific encoding

• Transports

  • src/transport/base.ts — transport port
  • src/transport/inmem.ts — in-memory exact-match broker + MQTT-filter broker

• Runtime components

  • src/runtime/edge_gateway.ts — mailbox ↔ internal bus bridge
  • src/runtime/component_host.ts — helper for registering internal "accepts" handlers
  • src/runtime/federation.ts — subscription leases + Evt forwarding
  • src/runtime/directory.ts — session directory + protocol facade
  • src/runtime/router.ts — hierarchical routing overlay bridge
  • src/runtime/discovery.ts + src/runtime/resolved_client.ts — endpoint resolution + fallback client

• Security building blocks

  • src/security/* — replay cache, rate limiter, policy hooks, principal derivation

• Tests

  • tests/unit/* — codecs and matching
  • tests/integration/* — end-to-end request/reply, subscriptions, directory push, discovery fallback, routing overlay, security