fix some docs

Author: micolous

cable-tunnel-server/README.md

@@ -1,14 +1,14 @@
 # webauthn-rs caBLE tunnel server
 
+**Important:** it is only necessary for an *authenticator vendor* to run a caBLE
+tunnel service for their devices. Initiators (such as browsers and client
+applications) connect to a tunnel service of the *authenticator's* choosing.
+
 **Warning:** this is still a work in progress, and not yet fully implemented.
 
 However, you can run a single-task tunnel service with the `backend` alone:
 [see `./backend/README.md` for instructions][0].
 
-**Important:** it is only necessary for an *authenticator vendor* to run a caBLE
-tunnel server for their devices. Initiators (such as browsers and client
-applications) connect to a tunnel server of the authenticator's choosing.
-
 [0]: ./backend/README.md
 
 ## Background
@@ -27,14 +27,14 @@ As far as the tunnel server is concerned, what happens is:
 
 2. The authenticator connects to a tunnel server of its choosing, using HTTPS.
 
-3. The authenticator makes a WebSocket request to `/cable/new/${TUNNEL_ID}`.
+3. The authenticator makes a WebSocket request to `/cable/new/${TUNNEL_ID}`[^new].
 
 4. The tunnel server responds with a WebSocket handshake, and includes a 3 byte
    routing ID in the HTTP response headers to indicate which task is serving
    the request.
 
-5. The authenticator transmits the tunnel server ID and routing ID as as an
-   encrypted Bluetooth Low Energy advertisement to the initiator.
+5. The authenticator transmits the tunnel server ID and routing ID to the
+   initiator using an encrypted Bluetooth Low Energy advertisement.
 
 6. The initiator decrypts the advertisement, and connects to the tunnel server
    using HTTPS.
@@ -44,8 +44,8 @@ As far as the tunnel server is concerned, what happens is:
 
 8. The tunnel server responds with a WebSocket handshake.
 
-9. The tunnel server relays WebSocket messages between the authenticator and
-   initiator.
+9. The tunnel server relays binary WebSocket messages between the authenticator
+   and initiator.
 
 The initiator starts a Noise channel with the authenticator for further
 communication such that the tunnel server cannot read their communications, and
@@ -56,6 +56,13 @@ limits, the tunnel server implementations are very simple. The tunnel server
 itself does not need to concern itself with the minutae of the Noise protocol -
 it only needs to pass binary messages across the tunnel verbatim.
 
+[^new]:
+  This [follows Google's caBLE URL convention][2]. The URL used to establish a
+  new channel [is not part of the FIDO 2.2 specification][3].
+
+[2]: https://source.chromium.org/chromium/chromium/src/+/main:device/fido/cable/v2_handshake.cc?q=symbol%3A%5Cbdevice%3A%3Acablev2%3A%3Atunnelserver%3A%3AGetNewTunnelURL%5Cb%20case%3Ayes
+[3]: https://fidoalliance.org/specs/fido-v2.2-rd-20230321/fido-client-to-authenticator-protocol-v2.2-rd-20230321.html#ref-for-client-platform①⓪
+
 ## Design
 
 `webauthn-rs`' caBLE tunnel server consists of three parts:
@@ -85,8 +92,8 @@ task.
 ### Frontend
 
 **Warning:** The `frontend` is not yet fully implemented, and does not yet do
-everything described here. This would be necessary for a larger scale deployment
-of a caBLE tunnel server.
+everything described here. This would be necessary to operate a
+high-availability caBLE tunnel service.
 
 **Source:** [`./frontend/`][frontend]
 

cable-tunnel-server/backend/README.md

@@ -62,13 +62,13 @@ To run the server with HTTPS and strict `Origin` header checks:
     --origin cable.example.com
 ```
 
-> **Important:** caBLE has an algorithm to deriving tunnel server domain names
-> -- you cannot host the service on arbitrary domain names of your choosing.
+> **Important:** caBLE has an algorithm to deriving tunnel server domain names –
+> you cannot host the service on an arbitrary domain name of your choosing.
 >
 > Run [`webauthn-authenticator-rs`' `cable_domain` example][cable_domain] to
 > derive hostnames at the command line.
 
-[cable_domain]: ../../webauthn-authenticator-rs/example/cable_domain.rs
+[cable_domain]: ../../webauthn-authenticator-rs/examples/cable_domain.rs
 
 ## Logging