texas2step 2.2.3__tar.gz → 2.3.0__tar.gz

{texas2step-2.2.3 → texas2step-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: texas2step
-Version: 2.2.3
+Version: 2.3.0
 Summary: Web-centric throughput, latency, jitter and packet-loss measurement between endpoints.
 Project-URL: Homepage, https://github.com/robert-patrick-texas/texas2step
 Project-URL: Documentation, https://robert-patrick-texas.github.io/texas2step/

{texas2step-2.2.3 → texas2step-2.3.0}/docs/access.md

@@ -18,7 +18,8 @@ no user names or passwords. The desk's own tools stay on your networks: saved re
   works out the same code from it, with nothing shared between them while they run.
 * **A code buys a pass.** The visitor enters the code once. The server answers with a
   pass, good for 12 hours (`access_pass_hours`), which the browser then sends with every
-  request, to every server in the picker. A server with the same key accepts it.
+  request, to every server in the picker. A server with the same key accepts it. To end
+  every pass at once, see [Ending every pass](#ending-every-pass).
 * **The desk's tools stay inside.** Visitors from addresses in `internal_networks` need no
   code, and only they get History, the API tab, saved results and the code itself.
   Everyone else gets the Test, Monitor and Diag tabs.
@@ -88,7 +89,8 @@ To turn codes off again: `sudo texas2step config set access_code=off --write`, t
 | `access_timezone` | `America/New_York` | The time zone whose midnight starts a new code; the same on every server |
 | `access_words` | `""` | Your own word list; empty uses the built-in words |
 | `access_digits` | `2` | The digits that end a code: 2, 3 or 4 |
-| `access_pass_hours` | `12` | How long an entered code lets a browser keep testing |
+| `access_pass_hours` | `12` | How long a pass lasts from when it was issued (1 to 168). Each server applies its own as passes are used, so a change applies to passes already given; use the same on every server. |
+| `access_note` | `Contact the service desk for assistance.` | The line under the code box, such as how to reach the desk; `""` for none |
 | `access_key_file` | `/etc/texas2step/access.key` | The key |
 | `access_phrases_file` | `/etc/texas2step/access-phrases.toml` | [Standing phrases](#standing-phrases), if the file exists |
 | `internal_networks` | `[]` | Your own networks: no code, and the desk's tools. A list of IPv4 and IPv6 addresses and networks in CIDR form, mixed freely: `["192.168.0.0/16", "2001:db8::/32", "203.0.113.7"]`. An address alone is a single host. Bits past the prefix are ignored, so `10.2.1.30/24` means all of `10.2.1.0/24`. Give the addresses as the server sees them: staff who come in through your firewall's NAT arrive from its public address. |
@@ -112,8 +114,9 @@ tests until it changes, but for a short list, or a `fixed` code, consider
 `access_digits = 3` or `4`.
 
 **When it changes.** A new code starts at midnight in `access_timezone`. The previous
-code keeps working for 24 hours after the change, for a call that spans midnight. A
-`fixed` code changes only with a new key:
+code keeps working for 24 hours after the change, for a call that spans midnight. To
+change it before then, or to change a `fixed` code, [shuffle the codes](#shuffling-the-codes),
+or make a new key:
 
 ```bash
 sudo texas2step access key --new
@@ -123,6 +126,42 @@ That makes a new key at once: every code and pass from the old one stops working
 the new key to the other servers as in step 1, and restart the service on each. Without
 `--yes`, it asks first.
 
+### Shuffling the codes
+
+When a code has gone further than it should, shuffle the codes. The current code and the
+previous one stop working at once, and a new one takes their place:
+
+```console
+$ sudo texas2step access shuffle
+Shuffle the codes? The current and previous codes stop working, and the desk reads the new one. [y/N] y
+Codes shuffled here. Today's code is now copper.lantern.42; the codes before it don't work.
+Passes already given keep working: add --end-passes to end them as well.
+Other servers: sent to dallas, houston.
+```
+
+A shuffle is a random value mixed into every code from then on. It is kept in
+`access_lockouts_file`, so it needs no new key and no restart, and outlasts a restart.
+Every code entered after it is checked against it, on every worker. The desk reads the
+new code at the top of History, or with `sudo texas2step access show`, which also says
+when the codes were shuffled. There is no previous code until the next change: at
+midnight, the shuffled code becomes yesterday's and works for 24 hours as usual. Phrases
+are not codes, so they keep working.
+
+Every server must hold the same shuffle, or they give different codes. With
+[servers that defend together](#servers-that-defend-together), it goes to every server in
+`[[locations]]`, and each keeps the latest it is given. Without them, the command prints
+the value for the others; run that on each:
+
+```bash
+sudo texas2step access shuffle --to 3f9a0c7e12b4d856
+```
+
+`access show`'s fingerprint includes the shuffle, so servers that agree show the same one.
+
+Passes already given keep working. Add `--end-passes` to [end them](#ending-every-pass)
+too, which has everyone outside enter the new code: the same as a new key, without
+copying a key to every server.
+
 **Typing it.** Case and separators don't matter: `Maple River 42`, `maple-river-42` and
 `maple.river.42` are the same code, and `7` counts for `07`.
 
@@ -204,7 +243,8 @@ journalctl -u texas2step --grep 'access phrase'
 stays guessable: several words that don't belong together, such as
 `copper lantern harbor violet`, rather than `vip access`. texas2step takes any phrase
 you choose. To withdraw one, `sudo texas2step access phrase remove vip` on every server,
-and restart; passes it already bought last until they expire (`access_pass_hours`).
+and restart. Passes it already bought last until they run out (`access_pass_hours`),
+unless you [end every pass](#ending-every-pass).
 A new key doesn't change the phrases.
 
 A phrase buys the same pass as the day's code, so the visitor gets what any visitor
@@ -234,18 +274,29 @@ texas2step run https://speedtest.example.net/texas2step --code maple.river.42
 
 | | Needs |
 |---|---|
-| The page at `/`, which asks for the code; its scripts, styles and logo; `/api/v1/health` (for load balancers, without the version); `/api/v1/access` | Nothing |
-| The Monitor and Diag pages, the tests, and saving a result | A pass, or an address in `internal_networks`. Without a pass, `/monitor` and `/diag` send the visitor to `/`. |
+| The page, at `/`, `/monitor` or `/diag`, which asks for the code; its scripts, styles and logo; `/api/v1/health` (for load balancers, without the version); `/api/v1/access` | Nothing |
+| The tests, Monitor and Diag's measurements, and saving a result | A pass, or an address in `internal_networks` |
 | History, the API tab, `/r/<id>`, reading saved results, `/api/docs`, `/api/openapi.json`, `/api/v1/measure/*`, the current code, [lockouts and blocks](#lockouts-and-blocks) | An address in `internal_networks`; others get 404 |
 
-The pass goes with every request the page makes, as `?pass=`. A page load can't carry
-that, so a right code also sets the pass as a cookie for the server's own pages:
-`HttpOnly`, `Secure` over HTTPS, `SameSite=Strict`, gone when the pass expires.
-
-Until a visitor enters a code, nothing tells them the version: the page leaves it out and
-`/api/v1/health` answers only `{"status":"ok"}`. Inside `internal_networks`, and once in,
-it is there as before. This slows an attacker down rather than stopping one: the page's
-scripts are those of a published release.
+The page keeps the pass in the browser's local storage and sends it with every request
+it makes. To its own server it goes in an `Authorization: Bearer` header, and a
+WebSocket's in its subprotocol, which keeps the pass out of the URLs that
+TLS-inspecting proxies log. To the other servers in the picker it goes as `?pass=`: a
+header there would make the browser ask permission (a CORS preflight) before each timed
+request and skew the timings. The server takes the pass in any of these, so the CLI's
+`?pass=` works as before. There is no cookie: a page needs no pass to load, and asks for
+the code itself. A cookie an earlier version set is removed at the next right code.
+
+With `internal_networks` set, only those networks see the version. The page,
+`/api/v1/info` and `/api/v1/health` leave it out for everyone else, even after they enter
+a code, and a result they save gets it from the server. Without `internal_networks`, a
+visitor sees it once they have entered a code; until then the page leaves it out and
+`/api/v1/health` answers only `{"status":"ok"}`. This slows an attacker down rather than
+stopping one: the page's scripts are those of a published release.
+
+The desk's functions also refuse, with `403`, a browser's request made for a page on
+another site, so that a website an employee opens can't use them through the employee's
+browser ([Security](security.md#the-desks-tools)).
 
 Loopback addresses are always inside, so commands on the server itself need no code. The
 service sees each visitor's address through nginx (`trusted_proxies`), which the packaged
@@ -262,6 +313,30 @@ inside.
 Without `internal_networks`, every visitor needs a code, and anyone with one can read the
 saved results. `texas2step access show` warns about that.
 
+### Inside on one address family
+
+A visitor with both IPv4 and IPv6 comes from two addresses, and `internal_networks` may
+list only one of them: an office's IPv6 network, say, but not the NAT address its IPv4
+leaves by. The page asks its own server, at the address it was opened at, whether the
+code is needed, and the browser reaches that over either family. When the answer is no
+but another address the page tests refuses it, the page asks for the code over itself,
+in a box the visitor can put aside with **Not now**. That other address is this server's
+IPv4-only or IPv6-only name ([IPv4 and IPv6](configuration.md#ipv4-and-ipv6)), or another
+server in the picker. The pass the code buys works over both families and on every
+server with the same key.
+
+The box comes up by itself until the visitor puts it aside, which holds until the page
+is loaded again. Meanwhile Test and Monitor say the function is restricted over that
+address, with a button to enter the code, and Diag's rows for it say **Restricted**, with
+the same button.
+Diag then tries that address every 10 seconds instead of every second, and opens no
+WebSocket there until the code is in. A server with `access_code = "off"` has no pass to
+give, so its page doesn't ask: it only says which address wants a code.
+
+A pass that hasn't run out but is refused anyway, as from a network blocked by hand
+([lockouts and blocks](#lockouts-and-blocks)), isn't asked for again by itself. To have
+neither family asked, list both of a site's addresses in `internal_networks`.
+
 ## Lockouts and blocks
 
 Wrong codes count against the visitor's network, its IPv4 /24 or IPv6 /48, not its
@@ -276,7 +351,8 @@ codes in a row from a network, it is locked out:
 * A network quiet for 30 minutes starts counting again from nothing, and so does one that
   enters a right code.
 * Visitors from `internal_networks` and loopback need no code, so they are never counted
-  or locked out. Passes already given keep working.
+  or locked out. Passes already given keep working through a lockout; a block set by hand
+  ends them (below).
 
 | Setting | Default | |
 |---|---|---|
@@ -324,6 +400,14 @@ longer if it keeps trying; blocking it again keeps it going. A block can't overl
 take effect at once, with no restart, and with
 [servers that defend together](#servers-that-defend-together), on every server.
 
+A block also ends the passes used from the network it covers. Until it ends, their
+requests are refused as if they carried none (`401`), and the WebSockets and UDP
+sessions they have open close within a few seconds. The page goes back to asking for the
+code, which the blocked network can't enter. A lockout from wrong codes ends no passes,
+so callers who share a network with a guesser keep testing with the pass they hold. A
+block set or ended through the API counts at once. One from the command line reaches
+each of the service's workers within 5 seconds, and so does one that ends.
+
 **From automation.** The same, as an API that answers only `internal_networks` and the
 server itself, so a script can carry a block from the server that saw an attack to all
 the others, and renew it there:
@@ -335,8 +419,9 @@ curl -s -X POST https://houston.example.net/texas2step/api/v1/access/blocks \
 curl -s -X DELETE 'https://houston.example.net/texas2step/api/v1/access/blocks?network=198.51.100.0/24'
 ```
 
-A list gives each lockout's `network`, `source`, `wrong_codes`, `since` and `until`, and
-`counting`, the networks with wrong codes in a row. A block that overlaps
+A list gives each lockout's `network`, `source`, `wrong_codes`, `since`, `until` and
+`by_hand` (a block, which ends passes too), and `counting`, the networks with wrong codes
+in a row. A block that overlaps
 `internal_networks`, or is wider than a /16 or a /32, is refused with `400`. These calls
 change only the server they are sent to; for one that reaches every server by itself, see
 [Servers that defend together](#servers-that-defend-together).
@@ -356,6 +441,44 @@ every 30 minutes. One with 10,000 networks gets about 1.4 million a day:
 For a server open to the Internet, use `access_digits = 4`, and standing phrases of
 several unrelated words.
 
+## Ending every pass
+
+A pass holds the time it was issued, signed with the key: `1793030400.q7GxN0x2rY8vLmKp3TfWcA9b`.
+No server keeps a list of them. Each server checks a pass as it is used:
+
+* The signature matches, so a server with the same key issued it.
+* It was issued less than `access_pass_hours` ago, by this server's setting now. Lower
+  the setting, and restart, and passes already given end sooner; raise it, and they last
+  longer.
+* It wasn't issued more than 5 minutes ahead of this server's clock.
+* It was issued after passes were last ended.
+
+To end every pass given so far, such as when a code or a phrase went further than it
+should have:
+
+```console
+$ sudo texas2step access passes --end
+End every pass issued so far? Everyone testing from outside enters the code again. [y/N] y
+Every pass issued before 2026-10-25 14:02 EDT is ended here, within seconds; tests running with one stop too.
+Other servers: sent to dallas, houston.
+```
+
+The time is kept in `access_lockouts_file`, beside the lockouts, so it needs no restart
+and outlasts one. Each of the service's workers reads it within 5 seconds. From then on,
+a pass issued before it is refused as if there were none (`401`), and the WebSockets and
+UDP sessions opened with one close within a few seconds. The page asks for the code
+again. The codes and phrases still work, so everyone with the current code is back in at
+once, with a new pass. Visitors from `internal_networks` need no pass, so nothing changes
+for them.
+
+With [servers that defend together](#servers-that-defend-together), the end goes to every
+server in `[[locations]]`, and each keeps the later of its own and the one it is sent.
+Without them, run the command on each server: until then, the others still take the
+passes. `sudo texas2step access passes` says how long passes last here and when they were
+last ended, and `access show` does too. To end the codes too, use
+`sudo texas2step access shuffle --end-passes` ([Shuffling the codes](#shuffling-the-codes)).
+A new key also ends every pass, and every code with it.
+
 ## Servers that defend together
 
 When a lockout begins on one server, the others can block that network too, so an
@@ -370,9 +493,12 @@ access_peer_networks = ["198.51.100.20", "2001:db8:20::20", "203.0.113.30"]
 * **What goes to the others.** A lockout here goes, as a block, to every server in
   `[[locations]]`, at once. While the attacker keeps trying here, it goes again every
   third of `access_lockout_minutes`, so the others' blocks don't run out first.
-  `sudo texas2step access block` and `access lockouts --clear` go to every server too:
-  `--clear` on any one of them lets a caller back in everywhere. The
-  [API's blocks](#lockouts-and-blocks) stay on the server they are sent to.
+  `sudo texas2step access block`, `access lockouts --clear`, `access passes --end` and
+  `access shuffle` go to every server too: `--clear` on any one of them lets a caller
+  back in everywhere. The
+  [API's blocks](#lockouts-and-blocks) stay on the server they are sent to. A block from
+  `access block` ends passes on every server, as here; a lockout ends none anywhere. A
+  server on an earlier version sends either as a lockout.
 * **What a server takes.** Only requests from an address in its `access_peer_networks`,
   signed with a key the servers work out from the access key they share. Use the
   addresses the other servers' requests leave from, which behind NAT may not be the
@@ -384,6 +510,10 @@ access_peer_networks = ["198.51.100.20", "2001:db8:20::20", "203.0.113.30"]
   compromised: a block from another server covers at most a /24 or a /48, never
   `internal_networks` or loopback, lasts at most a week, and isn't passed on. A server
   holds at most 1,000 of them. A wider block by hand stays on the server where it was set.
+  Another server can end every pass issued before its request, which at worst has
+  everyone enter the code again, but not set that time later than the receiving server's
+  clock allows, which would stamp new passes there too far ahead. It can shuffle the
+  codes, which at worst has the desk read the new one.
 * **Counts stay on each server.** Wrong codes count where they are entered, so with three
   servers an attacker gets up to about seven guesses, two at each and one more, before
   the whole cluster locks them out.
@@ -488,8 +618,7 @@ many as you need (`results_max_rows`). `sudo texas2step results clear` deletes t
 | Your `access_words` file | Yours: kept by `apt purge` |
 | `/var/lib/texas2step/access.db` | Wrong codes, lockouts and blocks, and with servers that defend together, the one-time values of their requests; made by the service when access codes are on; removed with `apt purge` |
 
-The pass lives in the visitor's browser (local storage, and the cookie for this server's
-pages) until it expires. Passes are not written to the journal: the request log shows
+The pass lives in the visitor's browser, in local storage, until it expires. Passes are not written to the journal: the request log shows
 `pass=*` in their place. nginx's access log doesn't have them either: the packaged
 snippets log texas2step's requests to `/var/log/nginx/access.log` without their query
 strings (the `texas2step` log format, in `/etc/nginx/conf.d/texas2step-log.conf`).

{texas2step-2.2.3 → texas2step-2.3.0}/docs/api.md

@@ -78,7 +78,8 @@ sending the offer. The offer must include data channels:
   profiles the session runs. A voice or video session counts toward a
   [traffic limit](traffic.md#monitors-call-profiles). The answer is
   `{"op":"profile","ok":true,"name":"voice"}`, or `"ok": false` with a `reason`: the
-  server withholds video (`monitor_video = false`), or a traffic limit is reached, when
+  server withholds that profile (`monitor_voice` or `monitor_video` is `false`, as
+  `/api/v1/info`'s `monitor` says), or a traffic limit is reached, when
   the site's `message` and `url` come with it. Past a limit while a session runs, the
   server sends `{"op":"limit","message":…,"url":…}` unasked and from then on echoes only
   probes of up to 64 bytes.
@@ -91,11 +92,11 @@ every port in its `rtc_port_min`–`rtc_port_max` range is taken.
 
 | Method | Path | Returns |
 |---|---|---|
-| GET | `/api/v1/info` | name, version, server identity, capabilities (`stamps`: the UDP probe can [stamp](#udp-probe-protocol) its echoes), limits, ICE servers, UI defaults (`one_stream`: whether a test downloads over one stream too, unless asked otherwise), `monitor` (`profile`: Monitor's until a visitor picks; `video`: whether the Video call profile is offered); with a [traffic limit](traffic.md), `traffic` (below) |
+| GET | `/api/v1/info` | name, version (left out for clients outside `internal_networks`), server identity, capabilities (`stamps`: the UDP probe can [stamp](#udp-probe-protocol) its echoes), limits, ICE servers, UI defaults (`one_stream`: whether a test downloads over one stream too, unless asked otherwise), `monitor` (`profile`: Monitor's until a visitor picks; `voice`, `video`: whether the Voice call and Video call profiles are offered); with a [traffic limit](traffic.md), `traffic` (below) |
 | GET | `/api/v1/whoami` | client IP, port, family, scheme, HTTP version, user agent |
 | GET | `/api/v1/diag/http` | both ends of this HTTP connection, its HTTP version and TLS, the server's TCP RTT and clock (below) |
 | GET | `/api/v1/locations` | servers offered in the picker (this one first) |
-| GET | `/api/v1/health` | `{"status": "ok", "version": …}`; without the version for clients that need an [access code](#access-codes) |
+| GET | `/api/v1/health` | `{"status": "ok", "version": …}`; without the version for clients outside `internal_networks`, or that need an [access code](#access-codes) |
 
 With a traffic limit, `traffic` says whether this client may start a test, and if not,
 what it is told:
@@ -175,21 +176,25 @@ curl -s -X POST https://dallas.example.net/texas2step/api/v1/measure/full \
 ## Access codes
 
 On a server with `access_code` on ([Access codes](access.md)), a client from outside
-`internal_networks` sends a pass as `?pass=<pass>` with each request under `/api/v1/`
-(except `/health` and `/access`); without a valid one it gets `401`. The WebSocket takes
-it the same way. With `internal_networks` set, clients from outside them get `404` for
+`internal_networks` sends a pass with each request under `/api/v1/` (except `/health`
+and `/access`); without a valid one it gets `401`. It goes as `?pass=<pass>`, or in an
+`Authorization: Bearer <pass>` header; a WebSocket can also carry it in its subprotocol,
+offering `texas2step` and `texas2step.pass.<pass>`, and is answered with `texas2step`. With `internal_networks` set, clients from outside them get `404` for
 reading results, `/api/v1/measure/*`, `/api/docs`, `/api/openapi.json`, the current code and
-the lockouts. `/api/v1/health` leaves out the version for clients that would need a pass.
+the lockouts, and the browser's requests to these made for a page on another site get
+`403`. With `internal_networks` set, `/api/v1/info` and `/api/v1/health` leave out the
+version for clients outside them; without them, `/api/v1/health` leaves it out for
+clients that would need a pass.
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/v1/access?pass=<pass>` | `{"required", "desk"}`: whether this client needs a pass, and gets the desk's functions; with `pass`, also whether that pass is valid and when it expires |
-| POST | `/api/v1/access` | `{"code": "maple.river.42"}` (any case and separators, or a standing phrase) returns `{"pass", "expires"}`, and sets the pass as a cookie for this server's pages. A wrong code is `403`. After `access_lockout_after` wrong codes in a row from one /24 or /48, every code from it gets that same `403`, unread, until `access_lockout_minutes` pass without one ([Lockouts and blocks](access.md#lockouts-and-blocks)). A body over 1 KB is `413` |
+| GET | `/api/v1/access?pass=<pass>` | `{"required", "desk", "codes", "note"}`: whether this client needs a pass, gets the desk's functions, and whether this server gives passes at all (`access_code` is on), and the site's line under the code box (`access_note`, empty for none); with `pass`, also whether that pass is valid and when it expires |
+| POST | `/api/v1/access` | `{"code": "maple.river.42"}` (any case and separators, or a standing phrase) returns `{"pass", "expires"}`. A wrong code is `403`. After `access_lockout_after` wrong codes in a row from one /24 or /48, every code from it gets that same `403`, unread, until `access_lockout_minutes` pass without one ([Lockouts and blocks](access.md#lockouts-and-blocks)). A body over 1 KB is `413` |
 | GET | `/api/v1/access/code` | The current code, when it changes, and the previous one while it still works; only from `internal_networks` |
-| GET | `/api/v1/access/blocks` | `{"lockouts": [{"network", "source", "wrong_codes", "since", "until"}], "counting"}`; only from `internal_networks` and the server itself |
-| POST | `/api/v1/access/blocks` | `{"network": "198.51.100.0/24", "minutes": 120}` locks a network out by hand, or keeps its lockout going; `minutes` defaults to `access_lockout_minutes`. One that overlaps `internal_networks`, or is wider than a /16 or a /32, is `400` |
+| GET | `/api/v1/access/blocks` | `{"lockouts": [{"network", "source", "wrong_codes", "since", "until", "by_hand"}], "counting"}` (`by_hand`: a block, which ends the passes used from the network too); only from `internal_networks` and the server itself |
+| POST | `/api/v1/access/blocks` | `{"network": "198.51.100.0/24", "minutes": 120}` locks a network out by hand, or keeps its lockout going, and ends the passes used from it; `minutes` defaults to `access_lockout_minutes`. One that overlaps `internal_networks`, or is wider than a /16 or a /32, is `400` |
 | DELETE | `/api/v1/access/blocks?network=<network>` | Ends the lockouts that overlap it (`all`: every one); returns `{"cleared": [...]}` |
-| POST | `/api/v1/access/peer` | For [servers that defend together](access.md#servers-that-defend-together): `{"from", "to", "action": "block" \| "clear" \| "check", "network", "minutes"}`, signed in `X-Texas2step-Time`, `-Nonce` and `-Signature`. Only from `access_peer_networks`, with `access_share_lockouts` on; `404` to everyone else |
+| POST | `/api/v1/access/peer` | For [servers that defend together](access.md#servers-that-defend-together): `{"from", "to", "action": "block" \| "clear" \| "check" \| "end-passes" \| "shuffle", "network", "minutes", "kind": "lockout" \| "block", "at", "value"}` (`kind`: a block set by hand, which ends passes there too; `lockout` when left out. `end-passes` ends every pass issued before `at`, in Unix seconds; `shuffle` mixes `value`, 16 hex digits, into the codes from `at`, the latest shuffle staying; neither `at` may be later than the receiving server's clock allows), signed in `X-Texas2step-Time`, `-Nonce` and `-Signature`. Only from `access_peer_networks`, with `access_share_lockouts` on; `404` to everyone else |
 
 ```bash
 pass=$(curl -s -X POST https://speedtest.example.net/texas2step/api/v1/access \

{texas2step-2.2.3 → texas2step-2.3.0}/docs/configuration.md

@@ -38,7 +38,8 @@ file up to date with the new version's template and keeps your values; see
 | `page_test` / `page_monitor` / `page_diag` / `page_history` / `page_api` | `true` | Show that tab of the web UI. Any can be hidden, but not all. A hidden page's address opens the first page shown. The API stays on: `results_enabled` and `measure_enabled` turn parts of it off, and `/api/docs` stays reachable without the API tab. |
 | `default_streams` / `default_seconds` / `default_packets` | 4 / 10 / 500 | Defaults advertised by `/api/v1/info` |
 | `monitor_profile` | `path` | Monitor's profile until a visitor picks one: `path` (small probes, to follow the path), `voice` or `video` (a call's packets, scored every 10 seconds); see [Live monitor](methodology.md#live-monitor) |
-| `monitor_video` | `true` | Offer Monitor's Video call profile, about 1.4 Mb/s each way while a tab runs it. Voice and video count toward a [traffic limit](traffic.md#monitors-call-profiles). |
+| `monitor_voice` | `true` | Offer Monitor's Voice call profile, about 150 kb/s each way while a tab runs it. With `false`, the page shows no Voice call button and the server refuses the profile. |
+| `monitor_video` | `true` | Offer Monitor's Video call profile, about 1.4 Mb/s each way while a tab runs it. With `false`, the page shows no Video call button and the server refuses the profile. With both `false`, Monitor runs Path only, and shows no profile switch. Voice and video count toward a [traffic limit](traffic.md#monitors-call-profiles). |
 | `default_one_stream` | `true` | Whether a test also downloads over [one stream](methodology.md#one-stream), unless the visitor chooses in Test options or the command line with `--one-stream` or `--no-one-stream`. It can add up to half again to a test's traffic, so a server whose traffic is billed may want `false`; see [Traffic limits](traffic.md#what-a-test-moves). |
 | `cors_origins` | `["*"]` | Origins allowed to call the API from a browser |
 | `trusted_proxies` | `["127.0.0.1", "::1"]` | Peers whose `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Prefix` and `X-Client-Protocol` are believed |
@@ -48,7 +49,8 @@ file up to date with the new version's template and keeps your values; see
 | `access_timezone` | `America/New_York` | The time zone whose midnight starts a new code |
 | `access_words` | `""` | A file of your own words for codes, one entry per line; empty uses the built-in words |
 | `access_digits` | 2 | The digits that end a code: 2, 3 or 4 |
-| `access_pass_hours` | 12 | How long an entered code lets a browser keep testing |
+| `access_pass_hours` | 12 | How long a pass lasts from when it was issued; applied as passes are used, so a change applies to passes already given. See [Ending every pass](access.md#ending-every-pass). |
+| `access_note` | `Contact the service desk for assistance.` | The line under the code box, such as how to reach the desk; `""` for none |
 | `access_key_file` | `/etc/texas2step/access.key` | The key codes come from; the same on every server of an organization |
 | `access_phrases_file` | `/etc/texas2step/access-phrases.toml` | Standing phrases that work as codes, if the file exists; see [Standing phrases](access.md#standing-phrases) |
 | `access_lockout_after` | 3 | Wrong codes in a row from one /24 or /48 that lock it out of entering codes; see [Lockouts and blocks](access.md#lockouts-and-blocks) |

{texas2step-2.2.3 → texas2step-2.3.0}/docs/install.md

@@ -51,7 +51,8 @@ To do the same by hand, follow steps 1 to 5 below instead.
    ```
 
    It logs to `texas2step-install.log` beside itself. When it finishes, the service
-   answers both on `127.0.0.1:8080` and through nginx, and it prints the address to open.
+   answers both on `127.0.0.1:8080` (or the `--port` you gave) and through nginx, and it
+   prints the address to open.
    You can run it again safely: it skips each step that is already done.
 
 What the check looks at, and what the script then does:
@@ -66,7 +67,7 @@ What the check looks at, and what the script then does:
 | Peers | Each `--peer URL` is asked who it is (`/api/v1/info`). A peer that can't be reached is left out, with the command to add it later. | `texas2step config add-location ... --write` |
 | nginx | nginx is installed and running, its configuration passes `nginx -t`, and it loads `conf.d/*.conf`. It finds your HTTPS site, and checks that nothing else on that site uses `/texas2step/`. If texas2step is already published, nginx is left alone. | Adds `include snippets/texas2step.conf;` after the site's `server_name` line, runs `nginx -t` and reloads. The file is backed up to `/var/backups/texas2step/` first, and put back if the test fails. |
 | UDP | The probe's port range: the one you set, or 61000–61999. It checks this range against the firewall and the kernel's ephemeral ports. | Pins the range in the settings. Opens it in ufw or firewalld if one of them is active. |
-| Port 8080 | Nothing else listens there | |
+| Port | Nothing else listens on texas2step's TCP port: 8080, `LISTEN_PORT` in `/etc/default/texas2step`, or `--port`. nginx's `upstream` in `/etc/nginx/conf.d/texas2step.conf` points at that port. | With `--port`, sets `LISTEN_PORT` and the `upstream` before the package is installed, so the service never starts on 8080. An `upstream` that points elsewhere is pointed at the port. |
 
 Options:
 
@@ -79,6 +80,7 @@ Options:
 | `--path PATH` | Publish texas2step at `PATH` instead of `/texas2step/`, e.g. `/speedtest`. The check moves the package's snippet to that path and shows it in the install script, which writes it as `snippets/texas2step-at-speedtest.conf` and includes that. Each later run writes it again from the new package. Use the same path in `--url-v4` and `--url-v6`. |
 | `--no-nginx` | Install the service only, and publish it yourself |
 | `--udp-ports MIN-MAX` | The probe's UDP range, e.g. `61000-61999` |
+| `--port PORT` | The TCP port texas2step listens on, on `127.0.0.1` behind nginx, when another program needs 8080. Choose one from 1024 to 32767. Later runs and `texas2step update` keep it. See [Another port](#another-port). |
 | `--url-v4 URL`, `--url-v6 URL` | This server's IPv4-only and IPv6-only base URLs, for the header's IP drop-down; see [IPv4 and IPv6](configuration.md#ipv4-and-ipv6). The check looks up each name: it should have only an A record (or only AAAA), pointing at this server. After the install, the script checks that nginx answers for each name. |
 | `--no-firewall` | Leave the firewall alone; the report lists the rule to add |
 | `--allow-downgrade` | Allow installing an older version than the one installed |
@@ -128,6 +130,32 @@ yourself.
 To make the second server by cloning the first's virtual machine instead, see
 [Clone a server](#clone-a-server).
 
+### Another port
+
+texas2step listens on `127.0.0.1:8080`, and nginx reaches it there through the
+`upstream` in `/etc/nginx/conf.d/texas2step.conf`. When another program needs 8080,
+give the setup tool another port, the same way for a new install or an installed server:
+
+```bash
+sudo ./texas2step-setup --port 8081
+sudo ./texas2step-install.sh
+```
+
+The install script sets `LISTEN_PORT=8081` in `/etc/default/texas2step` and points the
+`upstream` at `127.0.0.1:8081`, keeping a dated copy of each file it changes in
+`/var/backups/texas2step/`. It does this before installing the package, so the service
+never starts on 8080, even on a new install. Then it restarts texas2step, reloads nginx
+and checks both.
+
+Choose a port from 1024 to 32767. texas2step runs as its own user, which can't listen
+below 1024, and Linux takes the ports of outgoing connections from 32768 up. If the port
+is in use, the check says by what. Both files are kept on upgrades, and the setup tool
+and `texas2step update` read the port from `LISTEN_PORT`. When a new version changes the
+`upstream` file, the update installs the new one with your port in it.
+
+If you changed `LISTEN_PORT` by hand and not the `upstream`, the next run of the setup
+tool points the `upstream` at it.
+
 ## 1. Install the package
 
 Download the newest `.deb` from the
@@ -264,12 +292,11 @@ choose the default theme (Light, Dark, America, Energy, Federal, Military or Tex
 that site directly. Sites can also measure each other with `POST /api/v1/measure/full`,
 but only toward listed locations.
 
-**Listen address and workers.** These are set in `/etc/default/texas2step`. If you move
-the service off `127.0.0.1:8080`, change the `upstream` in
-`/etc/nginx/conf.d/texas2step.conf` to match. More workers help on multi-gigabit links,
-where Python's per-connection CPU cost is the limit. Each worker keeps its own UDP
-sessions, which is fine, because a session lives entirely in the worker that answered
-it.
+**Listen address and workers.** These are set in `/etc/default/texas2step`. To move the
+service to another port, see [Another port](#another-port). More workers help on
+multi-gigabit links, where Python's per-connection CPU cost is the limit. Each worker
+keeps its own UDP sessions, which is fine, because a session lives entirely in the
+worker that answered it.
 
 ## 4. Firewall and UDP
 

{texas2step-2.2.3 → texas2step-2.3.0}/docs/methodology.md

@@ -272,7 +272,10 @@ counted as lost. Statistics cover the visible window (1, 5 or 15 minutes).
 A **profile** sets what is sent. Anyone can switch it beside the Start button. Options
 holds the exact sizes and rates, and the page's address carries them, so the service
 desk can send a caller a link such as `/monitor?profile=voice`. The site picks the
-profile a visitor starts with (`monitor_profile`).
+profile a visitor starts with (`monitor_profile`), and can withhold the call profiles
+(`monitor_voice`, `monitor_video`): the switch then shows only the ones offered, and none
+at all when only Path is. A link or a saved choice for a withheld profile starts with
+the nearest one offered.
 
 | Profile | Sends | Each way, as the network carries it |
 |---|---|---|
@@ -365,6 +368,10 @@ and closes its connections. Its rows and events stay, and the timelines show the
 An attempt not answered within 2 s (1.5 s for WebSocket and UDP) counts as missed. A
 method that has answered before shows a miss as loss (red). One that hasn't answered
 yet stays grey and keeps trying. One the server doesn't offer is grey and isn't tried.
+One whose address asks for the access code, as a server's IPv4-only name can for a
+visitor inside on IPv6 only, says **Restricted** (amber) and doesn't count as loss:
+its HTTPS is tried every 10 s until the code is in, and no WebSocket is opened there
+meanwhile ([Inside on one address family](access.md#inside-on-one-address-family)).
 The clock offset is the server's time minus the browser's at the middle of the round
 trip, ± half the round trip.
 

{texas2step-2.2.3 → texas2step-2.3.0}/docs/roadmap.md

@@ -116,6 +116,29 @@ links and footer credit. Three places still say texas2step:
 
 Newest first. Each release's notes have the details and its upgrade steps.
 
+### [2.3.0](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.3.0) (2026-10-25)
+
+- [x] Passes carry when they were issued: `access_pass_hours` applies to passes already
+  given, and `texas2step access passes --end` ends every pass, on every server with
+  lockouts shared.
+- [x] `texas2step access shuffle` changes the codes at once, without a new key.
+- [x] A visitor inside on one address family and outside on the other is asked for the
+  code in a box over the page; Diag says which address is restricted.
+- [x] The code screen's words are the organization's, with `access_note` under the box.
+- [x] `texas2step-setup --port` for servers where another program needs 8080.
+- [x] `monitor_voice` withholds Monitor's Voice call profile, as `monitor_video` does
+  the Video call one.
+
+### [2.2.4](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.2.4) (2026-10-25)
+
+- [x] The desk's functions refuse requests made for pages on other sites; with
+  `internal_networks` set, only those networks see the version.
+- [x] API answers are kept in no browser cache.
+- [x] A block set by hand ends the passes used from its network, sessions already open
+  included.
+- [x] No cookie: the pass stays in local storage and goes to the page's own server in a
+  header; a Content-Security-Policy on the page and the API explorer.
+
 ### [2.2.3](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.2.3) (2026-10-24)
 
 - [x] Spaces around any setting or typed value are ignored; a stray one in

{texas2step-2.2.3 → texas2step-2.3.0}/docs/security.md

@@ -37,10 +37,20 @@ pass.
   the service (`0640 root:texas2step`). Anyone holding it can work out every code, so it
   is kept out of the world-readable `config.toml`. `texas2step access show` prints a
   fingerprint to compare servers by, which reveals nothing about the key.
-* **Passes.** A right code buys a pass for `access_pass_hours` (12 by default): an expiry
-  time signed with the key, checked by every server that holds it. The browser sends it
-  as `?pass=`; this server's own pages get it as a cookie that is `HttpOnly`,
-  `SameSite=Strict`, and `Secure` over HTTPS.
+* **Passes.** A right code buys a pass for `access_pass_hours` (12 by default): the time
+  it was issued, signed with the key, checked by every server that holds it against its
+  `access_pass_hours` as it is then. The page keeps it in
+  local storage, with no cookie, and sends it to its own server in an `Authorization`
+  header (a WebSocket's in its subprotocol), so it stays out of URLs that proxies log;
+  to the other servers, as `?pass=`. A pass is a bearer token: it isn't tied to
+  an address or a browser, and works until it runs out. A
+  [block set by hand](access.md#lockouts-and-blocks) ends it for the network blocked,
+  WebSockets and UDP sessions already open included.
+  [`texas2step access passes --end`](access.md#ending-every-pass) ends every pass issued
+  so far, on every server with lockouts shared, while the codes keep working.
+  [`texas2step access shuffle`](access.md#shuffling-the-codes) replaces the current and
+  previous codes with a new one, and with `--end-passes` ends the passes too. A new access
+  key ends every pass and code.
 * **Standing phrases.** For the desk away from a PC, in their own `0640` file
   (`access-phrases.toml`), with an optional last day. Each use is a journal warning with
   the phrase's name, never the phrase. The examples published in the docs are refused.
@@ -97,10 +107,22 @@ server itself), and `404` to everyone else, as if they weren't there:
 * the API explorer (`/api/docs`, `/api/openapi.json`);
 * the server-side measurements (`/api/v1/measure/*`).
 
+They also refuse, with `403`, a browser's request made for a page on another site. They
+trust the address a request comes from, and CORS lets any page read the answer, so a
+website an employee opens inside could otherwise read History, the current code and the
+blocks through that employee's browser, or set blocks. The browser says where a request
+came from in its `Sec-Fetch-Site` header, or, without one, in its `Origin`. A link from
+elsewhere still opens the desk's pages, because the other site can't read them. Scripts,
+the CLI and monitoring send neither header and work as before.
+
 Server-side measurements only reach the servers in `[[locations]]`, unless
 `allow_any_target` is set, so the server can't be used to make requests to other hosts.
 At most two run at once on each worker.
 
+**The version** would tell an attacker which flaws to try. With `internal_networks` set,
+only those networks see it: the page, `/api/v1/info` and `/api/v1/health` leave it out for
+everyone else, even after they enter a code. A result they save gets it from the server.
+
 ## Abuse of the service
 
 A speed test exists to move a lot of data, so each part has a cap:
@@ -138,6 +160,13 @@ A speed test exists to move a lot of data, so each part has a cap:
   figures) belong to the service user. The traffic figures hold no addresses.
 * **No third parties.** The web page loads nothing from other sites: no CDN, fonts,
   analytics or telemetry. No public STUN server is used unless listed in `ice_servers`.
+* **A Content-Security-Policy** on the page and the API explorer lets only their own
+  scripts run, and the one written into each page by its hash, and lets them connect
+  only to this server and the others in `[[locations]]`. A script injected some other
+  way can't run, or send what it finds to another site.
+* **Its own hostname.** A browser shares local storage across a whole origin, the scheme,
+  host and port. Where texas2step sits beside other applications on one hostname, any page
+  there could read the pass, so serve it from a hostname of its own where you can.
 
 ## Cryptography
 

{texas2step-2.2.3 → texas2step-2.3.0}/docs/traffic.md

@@ -142,7 +142,9 @@ acknowledgements the server sends back, as measured over IPv6. A tab left runnin
 When the limit is reached, the server holds those sessions to the small probes of the
 Path profile, which aren't counted, and Monitor says so with the site's message and link.
 Until the limit opens again, a call profile is refused at its start.
-`monitor_video = false` in the settings withholds the Video call profile altogether.
+`monitor_video = false` in the settings withholds the Video call profile altogether, and
+`monitor_voice = false` the Voice call one: the page doesn't offer them, and the server
+refuses them. With both, Monitor runs only the uncounted Path profile.
 
 ## What isn't counted
 

{texas2step-2.2.3 → texas2step-2.3.0}/src/texas2step/__init__.py

@@ -1,3 +1,3 @@
 """texas2step: web-centric throughput, latency, jitter and packet-loss measurement."""
 
-__version__ = "2.2.3"
+__version__ = "2.3.0"