async-matrix-bridge 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a39da8f7af838f517e3a60456691bf8dbcf5f69945a3f1f196bc2383ba5d3c07
-  data.tar.gz: fa6179dba22657736ba68f793838df46afcf72e861c25a9291e1677534910681
+  metadata.gz: 69434c46fa54930571a05c7cedf4797cdc1e608494f0c785c6c8c87a3dfe7e7d
+  data.tar.gz: e708c9852ea6a8baf87ce6651f09edb5a314da5fe3fb2394968654d95aec8808
 SHA512:
-  metadata.gz: 730ea22e8169a98f4e7a60da0db81af72769253a7fa9d0d288d3f33303323e2c1a09f8a00b2ff3187e86dfe757fee4b5baaba637d6dbe5e7c8cde4f96997c4ac
-  data.tar.gz: 30aa42aeff5abcee92b2707538e081797f89a81bf5f2dea2188d9948d7dfc4774dcda309c6dc46f7a793e3e4bda33d446e5ec78bbebec69ee3f4eb2e30fe2e9d
+  metadata.gz: 9d567fef4705acd06c3e50daad570ce07770236c864a9b606afd90c90cb594beee718c2d2fcc978bb16a1495e81461ad34beb053ccd18a5a8664679135196fa5
+  data.tar.gz: a0545367381d298e5f66a82cf3ffdb485fced43adc30bd66fd2580878d7364673cd9262558e4941389ab46ee007d5a3f0a0d8f7fc10b62635b62610a025dc1b4

data/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+
+## [3.0.0] - 2026-10-13
+
+A second ground-up pass, this time with async-rest as the only reference. The
+gem is five classes, the server side is middleware rather than a per-request
+object, and the events are async-matrix's own event classes rather than Hashes.
+
+### Added
+
+- `Bridge::Service` — a `Protocol::HTTP::Middleware` answering the application
+  service API, so it is served by an `Async::HTTP::Server` with no Rack
+  anywhere. One `case` on method and path, authentication by constant-time
+  compare of a Bearer token or the legacy `?access_token=`, and a `404` for
+  anything outside `/_matrix/app/v1` decided before authentication, so a
+  `/healthz` beside it is a `404` rather than a `403`. The user, room and
+  third-party queries are three blocks rather than three routes.
+
+- `Bridge::Transaction` — one pushed transaction as an
+  `Async::Matrix::Representation`, parsed with async-rest's own JSON parser and
+  typed through async-matrix's event registry. `each_room` groups a
+  transaction's events by room, in the order they arrived.
+
+- `Bridge::Puppet` — one user the service may act as, with `client`, `on` for
+  a device and `register!` / `device!` for provisioning it. A localpart outside
+  the registration's namespaces is refused locally.
+
+- `Registration#as` — identity assertion, as a resource derived with `#with`:
+  `user_id`, `device_id` (v1.17) and `ts` (v1.3) are parameters on the request
+  rather than a login. `bot` and `puppet` name the two identities a service
+  has.
+
+- `examples/bridge.rb` — a working two-way bridge between Matrix and a line
+  protocol, encrypted rooms included, and `examples/puppeting.rb` for identity
+  assertion on its own. The suite runs both against the homeserver in
+  `synapse/`, and asks the bridge whether each side heard the other.
+
+### Changed
+
+- `Registration.new(value, homeserver:)` and `Registration.load(path,
+  homeserver:)` take the homeserver URL alone. `domain:` is gone, derived from
+  it with `URI.parse` so the two cannot disagree.
+
+- `Registration#homeserver` is the URL string rather than a `Homeserver`
+  struct; `#domain` is the derived server name. The `Homeserver` and
+  `Appservice` structs are gone, so `registration.homeserver.address`,
+  `.homeserver.domain` and `registration.appservice.*` become
+  `registration.homeserver`, `.domain` and the readers on `Registration`
+  itself.
+
+- `Registration#raw` → `#value`, `Registration#bot_mxid` → `#sender` returning
+  the full MXID, `Registration#receive_ephemeral?` → `#ephemeral?`.
+
+- Namespace regexes match the whole of a name rather than part of one. A
+  service asks `covers?` to decide which senders are its own, and unanchored,
+  `@_bridge_.*` claimed `@notours_bridge_x:localhost` as well.
+
+- `async-matrix` is now `~> 4.0`, and `protocol-http` is a declared dependency
+  since a `Service` is one of its middlewares.
+
+### Removed
+
+- `Bridge::Endpoint`, and with it Rack, the Rack env input, the `concurrency:`
+  semaphore and the symbol-keyed Hashes. Events are objects a pattern reads by
+  class and field together.
+
+- `json_schemer` and the vendored registration schemas, and with them
+  `Registration.schema` and `Registration.validate!`. A registration is
+  validated by what it is asked for: the four required fields are checked at
+  construction, anything else is reached through `#value`.
+
+- `Registration#url`, `Registration#protocols`, `Registration#rate_limited?`
+  and `Registration#sender_localpart`. Readers for fields this service does not
+  act on, which the file still carries and `#value` still exposes.
+
+
+## [2.0.0] - 2026-10-09
+
+A ground-up replacement of the application service API. Everything is now one
+class, `Bridge::Endpoint`, driven by Ruby pattern matching, plus
+`Bridge::Registration` for configuration. The Grape-and-handler-objects stack
+is gone.
+
+### Added
+
+- `Bridge::Endpoint` — the whole AS wire protocol in one class. Built per
+  request from a Rack env *or* a `Protocol::HTTP::Request`, returning the
+  matching response type, so it serves a Rack stack and a bare
+  `Async::HTTP::Server` equally. It also defines `to_ary` so it can be
+  returned straight from a Rack router block, and `handled?` so it works as a
+  router's fall-through. Events reach the matcher block as symbol-keyed
+  Hashes, because Ruby hash patterns match Symbol keys only — which is what
+  lets `case/in` destructure nested `content:` with no `deconstruct_keys`
+  anywhere.
+
+- Concurrent dispatch. The events of a transaction run in their own fibers
+  under a bounded `Async::Semaphore` (`concurrency:`, default 8) and are all
+  awaited before the response, instead of running sequentially inline. Outside
+  a reactor dispatch falls back to sequential so the endpoint still works
+  under `Rack::MockRequest`.
+
+- `Bridge::Registration` — the registration file, validated against
+  `registration.json` and `namespace_list.json` vendored verbatim from
+  matrix-org/matrix-spec (`data/api/application-service/definitions/`). Those
+  are already JSON Schema draft 2020-12. Synapse ships no schema for this file
+  — it validates by hand in `synapse/config/appservice.py` — so the spec is
+  the only machine-readable source. Takes `homeserver:` and `domain:` as
+  required arguments and exposes `covers?`/`exclusive?` for namespaces.
+
+### Changed
+
+- **Namespace flattened.** `Async::Matrix::Bridge::ApplicationService::*` →
+  `Async::Matrix::Bridge::*`. The three classes sit directly on `Bridge`:
+  `Bridge::Endpoint`, `Bridge::Registration`, `Bridge::TransactionStore`.
+  There is no sub-namespace because there is nothing to distinguish it from
+  — the gem is the appservice protocol and nothing else. Bridge *domain*
+  concepts (portals, ghosts, provisioning) would be new peers if they ever
+  arrive, and the remote-network half of a bridge is inherently
+  application-specific.
+
+### Removed
+
+- `Server`, `Server::Grape`, `Bot`, `Bot::Handler`, `Bot::Context`,
+  `Dispatcher`, `TransactionHandler` and `Transaction`. `Bridge::Endpoint`
+  replaces all of them. The `#event_types`/`#call` handler duck-type, the
+  `on` DSL with its `msgtype:`/`not_from:` filters, handler registration and
+  the `thirdparty` duck-type are all gone: filtering is now `case/in` with
+  guards, and the long-standing `Dispatcher`/`TransactionHandler`
+  double-naming is resolved by deleting both.
+
+- `Config` and its 17-file mautrix bridgev2 JSON Schema suite.
+  `Bridge::Registration` replaces it, validating the application service
+  registration file against the Matrix spec's own schema. Configuration a
+  registration does not describe — `database`, `encryption`, `permissions`,
+  `backfill` — is no longer modelled here; `Config` remains available at the
+  `v1.0.0` tag.
+
+- Grape is no longer a dependency. `Bridge::Endpoint` speaks Rack and
+  Protocol::HTTP directly.
+
+### Fixed
+
+- **Transactions were silently dropped.** `json_body` re-read `rack.input`
+  after Grape's formatter middleware had already consumed it, and that
+  middleware only rewinds when the input responds to `#rewind` — which rack 3
+  streaming input (protocol-rack, so falcon and `Async::HTTP`) does not. Every
+  transaction parsed as `{}` and dispatched nothing while answering `200`. It
+  went unnoticed because `Rack::MockRequest` supplies a rewindable `StringIO`.
+
+- **A failing handler lost its events permanently.** The dispatcher logged
+  the exception, recorded the transaction id and returned `200`, so the
+  homeserver's retry was deduplicated away. `Bridge::Endpoint` answers `500`
+  and does not record the id, leaving the transaction retryable.

data/README.md

@@ -5,190 +5,127 @@
 [![License](https://img.shields.io/github/license/general-intelligence-systems/async-matrix-bridge)](https://github.com/general-intelligence-systems/async-matrix-bridge/blob/main/LICENSE)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-red)](https://www.ruby-lang.org)
 
-Async-native [Matrix](https://matrix.org) Application Service SDK for Ruby -- the server side of a bridge or bot. Built on [async-matrix](https://github.com/general-intelligence-systems/async-matrix) and the [Socketry](https://github.com/socketry) ecosystem (`async`, `async-http`). No threads, no callbacks -- just fibers.
+The application service side of [Matrix](https://matrix.org), for Ruby: the half of a bridge the homeserver pushes to, built on [async-matrix](https://github.com/general-intelligence-systems/async-matrix) and so on [async-rest](https://github.com/socketry/async-rest).
 
-Your homeserver `PUT`s transactions of events at your service; this gem authenticates them with a constant-time token compare, deduplicates them by transaction ID, and hands each event to a block you pattern match on -- concurrently, in its own fiber. Calls back to the homeserver go through async-matrix's `Client`.
-
-## Install
+A homeserver `PUT`s a transaction of events at your service. This gem authenticates it, drops a repeat of one it has already answered, types every event with async-matrix's own event classes and hands the transaction to your block. Everything the service says back to the homeserver it says through an async-matrix `Client`, as the user it is pretending to be.
 
 ```ruby
 gem "async-matrix-bridge"
 ```
 
-An `Endpoint` is not a Rack app and needs no Rack server. Add one only if you
-want to run it in a Rack stack:
+## The gem
 
-```ruby
-gem "ratalada", "~> 4.0"
-gem "protocol-rack"
-```
+Five classes, and nothing else:
 
-## Quick Start
+| Class | What it is |
+| --- | --- |
+| `Registration` | the registration file both ends read, and the identities it permits |
+| `Puppet` | one user the service may act as, with its own device |
+| `Service` | a `Protocol::HTTP::Middleware` answering the application service API |
+| `Transaction` | one pushed transaction, as a representation of typed events |
+| `TransactionStore` | which transaction IDs have been answered already |
 
-The whole protocol is one class, and the events reach a block you pattern match
-on. There is no handler to register, no filter DSL and no base class.
+## Serving
 
-```ruby
+`Service` is middleware rather than a Rack app, so it is the thing an `Async::HTTP::Server` serves. The block is handed a `Transaction`, and the events in it are async-matrix event objects: `case/in` reads them by class and by field together.
+
+``` ruby
 require "async/matrix/bridge"
-require "ratalada/async"
-
-Bridge = Async::Matrix::Bridge
-
-config = Bridge::Registration.load("/config/registration.yaml",
-  homeserver: "http://synapse:8008", domain: "localhost")
-
-client = Async::Matrix::Client.new(config)
-store = Bridge::TransactionStore.new
-bot = config.bot_mxid
-
-Server.run(host: "0.0.0.0", port: 9000) do |request|
-  Bridge::Endpoint.new(request, config: config, store: store) do |message|
-    case message
-    in {type: "m.room.member", content: {membership: "invite"}, room_id:, state_key: ^bot}
-      client.join_room(room_id)
-    in {type: "m.room.message", content: {msgtype: "m.text", body:}, room_id:, sender:} if sender != bot
-      client.send_notice(room_id, "Echo: #{body}")
-    else
-      nil
+
+registration = Async::Matrix::Bridge::Registration.load("registration.yaml", homeserver: "http://localhost:8008")
+
+service = Async::Matrix::Bridge::Service.new(registration) do |transaction|
+  transaction.each_room do |room_id, events|
+    events.each do |event|
+      case event
+      in {sender:, content: Async::Matrix::Events::TextMessage(body:)}
+        puts "<#{sender}> #{body}"
+      else
+        nil
+      end
     end
-  end.response
+  end
+end
+
+Async do
+  Async::HTTP::Server.new(service, Async::HTTP::Endpoint.parse("http://0.0.0.0:9000")).run
 end
 ```
 
-`Endpoint` also accepts a Rack env, so the same block works under any Rack
-server — pass `request.env` there instead.
+`each_room` groups a transaction's events by the room they belong to, in the order they arrived. `events` and `ephemeral` are the two lists the specification puts in a transaction; there is no third, which matters for encryption below.
 
-Working stacks with Synapse and Docker Compose live in
-[`examples/`](https://github.com/general-intelligence-systems/async-matrix-bridge/tree/main/examples).
+A homeserver pushes over HTTP/1.1 and will not do h2c with prior knowledge, so a listener pinned to HTTP/2 never receives anything.
 
-## Pattern matching
+The queries are three blocks rather than three routes. Each answers whether the service has something, and `nil` is `M_NOT_FOUND`:
 
-The block is handed plain **symbol-keyed** Hashes. That is deliberate: Ruby's
-hash patterns match Symbol keys only, so `in {type: "m.room.message"}` would
-never match a `{"type" => ...}` parsed from JSON. Parsing with
-`symbolize_names` is what makes `case/in` destructure nested content with no
-`deconstruct_keys` on anything.
+``` ruby
+service.query_user{|user_id| registration.covers?("users", user_id)}
+service.query_room{|room_alias| room_alias == "#_bridge_lobby:localhost"}
+```
 
-The filters that used to be DSL options are now ordinary pattern syntax -- a
-pin for "addressed to me", a guard for "not from me":
+A path outside `/_matrix/app/v1` is a `404` before anything is authenticated, so the service composes as the fall-through of a router which has its own routes.
 
-```ruby
-in {type: "m.room.member", content: {membership: "invite"}, state_key: ^bot}
-in {type: "m.room.message", content: {msgtype: "m.text", body:}, sender:} if sender != bot
-```
+If your block raises, the response is `500` and the transaction ID is **not** recorded, so the homeserver retries it. Recording it would make one failed handler drop those events for good.
 
-Third-party protocol, location and user queries reach the same block as a
-`:query` Hash, so one `case` covers the whole protocol. Whatever it returns is
-the JSON body; `nil` is `M_NOT_FOUND`.
+## Acting as somebody
 
-```ruby
-in {query: :protocol, protocol:}
-  {instances: instances_for(protocol)}
-```
+A service does not log in. It asserts an identity: its own token says which service, and the user is a parameter on the request. `Registration#as` is that, and `Puppet` is one user it may act as.
 
-## Without Rack
+``` ruby
+puppet = registration.puppet(client, "_bridge_ripley")
 
-`Endpoint` takes either a Rack env or a `Protocol::HTTP::Request`, and answers
-with whichever response type the source implies. So the same class drops into a
-bare `Async::HTTP::Server` with no Rack anywhere in the stack:
+puppet.register!
+puppet.device!("RIPLEY1", display_name: "ripley")
 
-```ruby
-server = Async::HTTP::Server.for(endpoint) do |request|
-  Bridge::Endpoint.new(request, config: config, store: store) do |message|
-    case message
-    in {type: "m.room.message", content: {body:}, room_id:}
-      client.send_notice(room_id, "Echo: #{body}")
-    else
-      nil
-    end
-  end.response
-end
+puppet.client.join_room(room_id)
+puppet.on("RIPLEY1").room(room_id).send_message(content.type, content.to_h)
 ```
 
-Do not pin the server to HTTP/2: homeservers push transactions over HTTP/1.1
-and will not do h2c with prior knowledge, so a forced-HTTP2 listener never
-receives an event.
+`puppet.client` is the user; `puppet.on(device_id)` is the user at one of its devices, which is what keys belong to. Both take `ts:`, which is how a bridge gives a message the time it was really said. A localpart outside the registration's namespaces is refused here rather than at the homeserver.
 
-## Your own routes
+Every one of those is an ordinary async-matrix call on a resource derived with `#with`. This gem adds no helpers of its own for talking to the homeserver, and it has no opinion about which calls a bridge makes.
 
-An `Endpoint` answers `404` for any path outside `/_matrix/app/v1`, so it works
-as the fall-through of a router that matches its own routes first. Ask
-`handled?` if you would rather compose explicitly.
+## Encryption
 
-```ruby
-Server.run do |request|
-  case request
-  in ["GET", "/healthz"] then "ok\n"
-  else Bridge::Endpoint.new(request, config: config, store: store) { |message| ... }.response
-  end
-end
-```
+A transaction carries `events` and `ephemeral`, and no keys at all. So nothing pushed to a service can be decrypted by anything that push told it — and the specification is explicit about the way in: a service which wants `/sync` syncs as one of its own users.
 
-## Concurrency and retries
-
-The events of a transaction are dispatched in their own fibers, bounded by
-`concurrency:` (default 8), and all of them are awaited before the response.
-
-If the block raises, the response is `500` and the transaction id is **not**
-recorded, so the homeserver retries it. Recording it and answering `200` would
-make a failed handler drop its events permanently, since the retry would be
-deduplicated away.
-
-## Configuration
-
-`Registration` reads the application service registration file -- the one your
-homeserver already loads -- and validates it against the Matrix spec's own
-schema, vendored verbatim from
-[matrix-org/matrix-spec](https://github.com/matrix-org/matrix-spec/tree/main/data/api/application-service/definitions).
-Nothing is restated: the tokens, the sender localpart and the namespaces are
-read from the file the homeserver reads.
-
-```yaml
-# registration.yaml -- give this to your homeserver
-id: agent
-url: "http://appservice:9000"
-as_token: "your-appservice-token"
-hs_token: "your-homeserver-token"
-sender_localpart: agent
-namespaces:
-  users:
-    - exclusive: false
-      regex: "@.*:localhost"
-  aliases: []
-  rooms: []
-```
+So an encrypted bridge has two inputs which meet in one machine's store. The ciphertext is pushed, the keys are pulled, and neither input knows about the other:
 
-```ruby
-config = Bridge::Registration.load("registration.yaml",
-  homeserver: "http://synapse:8008", domain: "localhost")
+- the `Service` block hands the ciphertext to the machine, which defers what it cannot read yet,
+- a sync loop, running as a puppet, pulls the to-device traffic the keys arrive in, and the key releases the deferred event.
 
-config.bot_mxid                              # => "@agent:localhost"
-config.covers?(:users, "@alice:localhost")   # => true
-config.exclusive?(:users, "@alice:localhost") # => false
-```
+Synapse answers `/sync` for the service's own user with a `500`, so the user which reads is a puppet rather than the sender localpart. [`examples/bridge.rb`](examples/bridge.rb) is that, whole and working, in one file.
+
+## The examples
+
+Both examples run against the homeserver in `synapse/`, and the suite runs them:
+
+- [`examples/bridge.rb`](examples/bridge.rb) — a bridge, both ways, between Matrix and a line protocol. A nick on the other network gets a user and a device of its own; an encrypted room is encrypted to, by claiming a key from every device and sharing a Megolm session over Olm; what Matrix says comes back out of the socket.
+- [`examples/puppeting.rb`](examples/puppeting.rb) — identity assertion on its own: the service's own user, a puppet, a device, published keys, cross-signing, timestamp massaging, and the refusal of a user outside the namespaces.
 
-`homeserver:` and `domain:` are separate arguments because a registration
-describes the service *to* the homeserver and so cannot carry the server's own
-address. `domain` is required rather than inferred from the URL: a
-`server_name` need not match the host it is served from, and a wrong guess
-yields plausible, broken MXIDs.
+``` bash
+REGISTRATION=./synapse/appservice.yaml HOMESERVER=http://localhost:7400 CHANNEL=lobby ENCRYPTED=true ruby examples/bridge.rb
+
+printf 'ripley\nhello from the network\n' | nc localhost 9100
+```
 
 ## Development
 
-```bash
-bin/test      # scampi, co-located `__END__` specs
+``` bash
+bin/test      # brings the homeserver up, then runs sus
 bin/rubocop
 ```
 
-async-matrix is an ordinary RubyGems dependency -- it resolves from RubyGems like any other gem, including inside the Nix devshell. To try a change to the core gem against this one, publish a prerelease of it, or `bundle config local` a git checkout; do not add a `path:` entry to the Gemfile. `bundlerEnv` cannot resolve a relative path source pointing outside the flake, so a path gem breaks `nix develop` outright.
+`bin/test` recreates the container rather than reusing it: its database is in tmpfs, and a transaction which failed once puts the homeserver's scheduler into a backoff reaching 512 seconds, which an example started afterwards would be waiting on rather than on itself.
+
+async-matrix is an ordinary RubyGems dependency. To try a change to it against this gem, publish a prerelease or `bundle config local` a git checkout; do not add a `path:` entry to the Gemfile, because `bundlerEnv` cannot resolve a path source pointing outside the flake and `nix develop` then fails outright.
 
-## Built With
+## Built with
 
-- [async-matrix](https://github.com/general-intelligence-systems/async-matrix) -- the Matrix protocol layer (client, events, media, E2EE)
-- [async](https://github.com/socketry/async) -- fiber-based concurrency framework
-- [protocol-http](https://github.com/socketry/protocol-http) -- the HTTP semantics `Endpoint` answers in
-- [json_schemer](https://github.com/davishmcclurg/json_schemer) -- JSON Schema validation
-- [scampi](https://github.com/general-intelligence-systems/scampi) -- inline co-located test framework
+- [async-matrix](https://github.com/general-intelligence-systems/async-matrix) — the Matrix protocol layer: clients, events, E2EE
+- [async-rest](https://github.com/socketry/async-rest) — resources and representations, which this gem's are
+- [protocol-http](https://github.com/socketry/protocol-http) — the middleware a `Service` is
+- [async](https://github.com/socketry/async) — fibers
 
 ## License
 

data/lib/async/matrix/bridge/puppet.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    module Bridge
+      # One of the service's own users, and what it takes to bring them into existence.
+      #
+      # A puppet is made twice over. Registering makes the user, and a homeserver refuses to act as
+      # one it was never told about. Creating a device makes something which can hold keys, which
+      # from v1.17 a service does itself rather than logging in for.
+      class Puppet
+        # The login type which says a service is asking, rather than a person with a password.
+        LOGIN_TYPE = "m.login.application_service"
+
+        # What a homeserver answers when the user is already there, which is not a failure here.
+        IN_USE = "M_USER_IN_USE"
+
+        # @parameter registration [Registration] the service this user belongs to.
+        # @parameter client [Async::Matrix::ClientServer::Client] an unauthenticated client.
+        # @parameter localpart [String] the part of the ID which names them, without the sigil.
+        def initialize(registration, client, localpart)
+          @registration = registration
+          @client = client
+          @localpart = localpart
+
+          # Refused here rather than by the homeserver: the namespaces say which users this service
+          # may act as, so a localpart outside them is a mistake in the caller rather than a request.
+          unless registration.covers?("users", self.user_id)
+            raise ArgumentError, "#{self.user_id} is outside this service's namespaces!"
+          end
+        end
+
+        # @attribute [String] the part of the ID which names them.
+        attr :localpart
+
+        # @returns [String] the fully qualified ID of this user.
+        def user_id = "@#{@localpart}:#{@registration.domain}"
+
+        # A client which acts as this user, on no particular device.
+        #
+        # @parameter ts [Integer | nil] when what is sent through it happened, in milliseconds.
+        # @returns [Async::Matrix::ClientServer::Client] the client.
+        def client(ts: nil) = @registration.as(@client, self.user_id, ts: ts)
+
+        # A client which acts as this user on one of their devices, which is what encryption needs.
+        #
+        # @parameter device_id [String] the device to act as.
+        # @parameter ts [Integer | nil] when what is sent through it happened, in milliseconds.
+        # @returns [Async::Matrix::ClientServer::Client] the client.
+        def on(device_id, ts: nil) = @registration.as(@client, self.user_id, device_id: device_id, ts: ts)
+
+        # Make the user, which is what lets the service act as them at all.
+        #
+        # Asking twice is not an error: a service does not remember which of its users it has made,
+        # and a homeserver which already has one says so rather than failing.
+        #
+        # @returns [Boolean] whether this call is what made them.
+        def register!
+          @registration.as(@client).registration.register(username: @localpart, type: LOGIN_TYPE)
+
+          true
+        rescue Async::Matrix::RequestError => error
+          unless error.errcode == IN_USE
+            raise
+          end
+
+          false
+        end
+
+        # Make one of their devices, so there is something to hold keys and to act as.
+        #
+        # Asked as the user rather than as the device: acting as a device the homeserver has not got
+        # is what this call is here to fix, so it cannot be how the call is made.
+        #
+        # @parameter device_id [String] the device to make.
+        # @parameter display_name [String] what a user of the other network would recognise.
+        # @returns [Async::Matrix::Representation] the empty response.
+        def device!(device_id, display_name: @localpart)
+          self.client.devices.update_device(device_id, display_name: display_name)
+        end
+
+        def inspect = "\#<#{self.class} #{self.user_id}>"
+      end
+    end
+  end
+end