# @open-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

```bash
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 + wildcard-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