Merge pull request #7 from q1ngyang/codex/patch-v1.3.1-fastmedia-pairing

release: Starry patch-v1.3.1 preview

Author: q1ngyang

.github/workflows/build.yml

@@ -0,0 +1,5 @@
+# Deterministic public Ed25519 key used only by the isolated package smoke test.
+# Keep this exception pinned to the reviewed historical commit, path, rule, and line.
+e7fe43142f1602612ca118f241ae84087b5cb461:.github/workflows/build.yml:generic-api-key:667
+# The same public fixture in the uncommitted candidate working-tree scan.
+.github/workflows/build.yml:generic-api-key:667

.gitleaksignore

@@ -1 +1 @@
-1.3.0
+1.3.1

PATCH_VERSION

@@ -29,17 +29,19 @@ Starry extends **HBBS** with:
 - certificate-verified `/ws/relay` health filtering;
 - Akari-only candidate Relay active probing with dual-end RTT/jitter/loss and
   trusted HBBR load scoring, prefix-cache hysteresis, and a legacy single-Relay fallback;
-- default-off, short-lived Ed25519 authorization for Akari P2P fast mode's
-  FastCompat path after exact auth allow and final Relay selection; the first
-  v1 release explicitly keeps FastMedia Relay UDP disabled;
+- default-off, short-lived Ed25519 authorization for Akari FastCompat and
+  role-bound FastMediaV1 after exact auth allow and the final server-selected
+  Relay, with a separately supervised HBBR AKR1 UDP data plane;
 - generation-safe Profile Activation Leases for Akari, including a matching
   Ready ACK, explicit current-lease deactivation, bounded verified rapid
   re-registration, and official-client-compatible defaults;
-- schema v4 last-known-good activation with generation, digest, and synchronous
+- schema v5 last-known-good activation with generation, digest, and synchronous
   subsystem acknowledgements;
 - optional strict Ed25519 connection JWT audit/enforcement for both
   `PunchHoleRequest` and direct `RequestRelay` on native TCP, Secure TCP, and
   WSS, with UDP initiation explicitly unsupported; and
+- SP1 Control-Agent/Relay bootstrap, bounded Relay enrollment, persistent
+  identities, and a no-side-effect v5-to-v4 downgrade export; and
 - immutable Relay snapshots, side-effect-free allocation simulation, plus a
   separate Linux Control Agent protected by mTLS, scoped service JWTs, and
   atomic configuration transactions.
@@ -49,24 +51,28 @@ The project deliberately keeps the component boundary narrow:
 | Component | Starry scope | Deployment responsibility |
 | --- | --- | --- |
 | HBBS | Modified by the overlay | Run the Starry `hbbs` binary or image command. |
-| HBBR | Public probe plus authenticated telemetry | Keeps the upstream byte-forwarding data path, answers the additive Akari probe envelope without load details, and exposes bounded session/bandwidth telemetry only to authenticated HBBS pulls. Use the HBBR bundled in the same pinned Starry image/artifact. |
+| HBBR | Reliable Relay plus optional AKR1 UDP | Keeps the upstream TCP/WS byte-forwarding path, answers public quality probes without load, exposes detailed state only through authenticated telemetry, and optionally routes encrypted Akari AKF1 datagrams after role-bound grants. |
 | Control Agent | Optional Starry component; Linux only in v1.3 | Keep HBBS local control on loopback. Expose the Agent only on a private management path with mTLS and scoped service JWTs. Configuration writes are disabled by default. |
 | Account/API server | Not included | Account login, address books, device data, and administration require a separately selected API implementation. |
 
 An account API login, the HBBS signalling connection, the optional Starry
 Control API, and the HBBR data path are separate protocol layers. Starry does
-not turn a third-party API into a Relay, does not alter the HBBR relay data
-path, and does not replace the RustDesk client.
+not turn a third-party API into a Relay and does not replace the RustDesk
+client. The optional FastMedia UDP listener is independent from the ordinary
+HBBR stream, which always remains the reliable fallback.
 
-Current development release: **patch-v1.3.0**. See the
-[`patch-v1.3.0` release notes](docs/releases/RELEASE-NOTES-patch-v1.3.0.md) and
+Current development release: **patch-v1.3.1 preview**. See
+the [`patch-v1.3.1` release notes](docs/releases/RELEASE-NOTES-patch-v1.3.1.md) and
 [`changelog`](docs/releases/CHANGELOG.md). Docker images are published at
 [`ghcr.io/q1ngyang/rustdesk-server-starry`](https://github.com/q1ngyang/rustdesk-server-starry/pkgs/container/rustdesk-server-starry).
 
-The patch-v1.3.0 supported release matrix is Docker `linux/amd64` plus Linux
+The patch-v1.3.1 candidate matrix is Docker `linux/amd64` plus Linux
 x86_64 binaries and amd64 DEB packages. ARM is best-effort source
 compatibility; Windows is an experimental non-blocking build. Neither is a
-promised v1.3.0 artifact.
+promised v1.3.1 artifact. The preview is opt-in, keeps both Fast switches off
+by default, and is published only as a GitHub prerelease and the rolling
+`preview` image. Stable approval still requires the end-to-end FastMedia and
+real-device release gates.
 
 > This is an unofficial community project and is not affiliated with or
 > endorsed by RustDesk, MaxMind, any MMDB mirror provider, or any AI service
@@ -99,6 +105,9 @@ sources, container manual, release notes, and technical references.
 | [Connection authentication](https://github.com/q1ngyang/rustdesk-server-starry/wiki/Connection-Authentication) | JWT profile, audit-to-enforce rollout, transport coverage, failure handling, and rollback. |
 | [Control Agent](https://github.com/q1ngyang/rustdesk-server-starry/wiki/Control-Agent) | Linux deployment, mTLS/service-JWT authorization, read-only mode, transactions, recovery, and API contracts. |
 | [Profile Activation Lease v1](docs/reference/PROFILE-ACTIVATION-LEASE-v1.md) | Akari matching-ACK switch rule, current-route deactivation, multi-node leases, observability, rollout, and rollback. |
+| [Fast Relay authorization v1](docs/reference/FAST-RELAY-AUTHORIZATION-v1.md) | Server-selected Relay grants, additive fields 1–12, compatibility, privacy, and issuance gates. |
+| [FastMedia Relay UDP v1](docs/reference/FAST-MEDIA-RELAY-UDP-v1.md) | AKR1 cookie/bind/forward/rebind wire and resource contract. |
+| [Starry Pairing v1](docs/reference/STARRY-PAIRING-v1.md) | SP1 Control Agent/Relay bootstrap, persistence, manual compatibility, and downgrade. |
 | [GEO rules: basics](https://github.com/q1ngyang/rustdesk-server-starry/wiki/GEO-Rules-Basics) | Country rules, priority, symmetry, fallback, and `test-geo`. |
 | [GEO rules: advanced](https://github.com/q1ngyang/rustdesk-server-starry/wiki/GEO-Rules-Advanced) | City, ASN, ISP, nested expressions, quoting, and design patterns. |
 | [Operations and verification](https://github.com/q1ngyang/rustdesk-server-starry/wiki/Operations-and-Verification) | Layered checks from static validation to real desktop sessions. |

README.md

@@ -1,7 +1,10 @@
-# patch-v1.3.0 was approved for publication on 2026-09-02 after the reviewed
-# candidate passed every blocking compatibility, security, and release gate.
-status: APPROVED
-patch_version: 1.3.0
+# The frozen wire/Control contract remains bound to commit
+# 6f5a31008ab7761d8557c8cf9fefcb5be11c49e6. Source and protocol-level
+# validation permit an opt-in preview release. Stable publication remains
+# blocked until the real two-client/device/network and production PKI matrices
+# pass. PREVIEW_APPROVED publishes a GitHub prerelease and the rolling
+# `preview` image only; it never replaces `latest`.
+status: PREVIEW_APPROVED
+patch_version: 1.3.1
 
-# Publication remains fail-closed until every required workflow job succeeds
-# again for the exact source commit that receives the immutable release tag.
+# Do not change this to APPROVED from preview or diagnostic validation alone.

RELEASE_STATUS

@@ -2,7 +2,7 @@
 # Copy the required sections to config.yaml. An empty or invalid config.yaml
 # keeps the exact upstream rustdesk-server behavior on first start. A rejected
 # reload retains the last-known-good active generation.
-version: 4
+version: 5
 
 # The complete HBBS relay pool. Keep one relay server on each line.
 relay_servers:
@@ -55,12 +55,15 @@ websocket_signal:
       - relay: jp-relay-1.example.com:21117
         url: wss://jp-relay-1.example.com/ws/telemetry
         telemetry_secret_file: /run/secrets/starry-relay-telemetry
+        fast_media_udp_port: 21119
       - relay: jp-relay-2.example.com:21117
         url: wss://jp-relay-2.example.com/ws/telemetry
         telemetry_secret_file: /run/secrets/starry-relay-telemetry
+        fast_media_udp_port: 21119
       - relay: us-relay-1.example.com:21117
         url: wss://us-relay-1.example.com/ws/telemetry
         telemetry_secret_file: /run/secrets/starry-relay-telemetry
+        fast_media_udp_port: 21119
 
 # Connection authentication requires schema v3 or newer and defaults to off. Move to
 # audit before enforce, and do not enable either mode until Kessoku (or another
@@ -125,14 +128,19 @@ relay_quality:
     loss: 2500
     load: 1500
 
-# FastCompat authorization for Akari over the existing reliable HBBR stream.
-# Keep this disabled until connection authentication and Relay quality are both
-# enabled and verified. FastMediaV1 Relay UDP is deliberately not advertised.
+# FastCompat authorization keeps using the reliable HBBR stream. FastMediaV1
+# uses an optional AKR1 UDP path while the reliable stream remains connected.
+# Both switches are independent and default to false. Relay Quality remains
+# authoritative when it produces a final decision; otherwise HBBS signs only
+# the Relay it selected itself. FastMedia grants additionally require fresh,
+# authenticated schema-v2 telemetry from that selected HBBR.
 fast_mode:
   relay:
     fast_compat_enabled: false
+    fast_media_v1_enabled: false
     authorization_ttl_seconds: 90
     max_bitrate_kbps: 50000
+    relay_max_datagram: 1200
 
 mmdb:
   update_interval_hours: 168

config/config.example.yaml

@@ -1,26 +1,26 @@
 # Starry Control Agent v1. Keep this listener on a Kessoku-only private
 # interface. HBBS itself is reached exclusively through loopback local control.
 version: 1
-instance_id_file: /var/lib/rustdesk-server-starry/control-agent-instance-id
+instance_id_file: /var/lib/rustdesk-server-starry/control/state/instance-id
 listen: 127.0.0.1:21120
 
 tls:
-  ca_file: /etc/rustdesk-server-starry/control-tls/client-ca.pem
-  cert_file: /etc/rustdesk-server-starry/control-tls/server.pem
-  key_file: /etc/rustdesk-server-starry/control-tls/server-key.pem
+  ca_file: /etc/rustdesk-server-starry/control-identity/client-ca.pem
+  cert_file: /etc/rustdesk-server-starry/control-identity/server-cert.pem
+  key_file: /etc/rustdesk-server-starry/control-identity/server-key.pem
   allowed_client_uri_sans:
     - spiffe://kessoku.example/starry-control
 
 # This keyring is separate from connection_auth.jwks. It verifies short-lived
 # Kessoku service tokens, never RustDesk client connection tokens.
 service_jwt:
   issuer: https://kessoku.example
-  jwks_file: /etc/rustdesk-server-starry/control-auth/jwks.json
+  jwks_file: /etc/rustdesk-server-starry/control-identity/service-jwks.json
   audience_prefix: "urn:starry-control:"
 
 local_control:
   address: 127.0.0.1:21115
-  token_file: /etc/rustdesk-server-starry/local-control.token
+  token_file: /var/lib/rustdesk-server-starry/control/shared/local-control.token
 
 config:
   # Safe default. Set true only after apply/rollback recovery has been tested.